dp1

README

dp1-go

Go SDK for the DP-1 protocol: playlists, playlist-groups (exhibitions), ref manifests, JCS signing payloads (RFC 8785), Ed25519 verification (legacy + multi-signature), and registered JSON Schema extensions.

Module: github.com/display-protocol/dp1-go

Requirements

• Go 1.22+

Install

go get github.com/display-protocol/dp1-go

Usage

Parse and validate

All entrypoints validate raw JSON against embedded JSON Schema (draft 2020-12), then decode into typed structs.

Function	Document
ParseAndValidatePlaylist	Core playlist
ParseAndValidatePlaylistWithPlaylistsExtension	Core playlist + playlists extension overlay
ParseAndValidatePlaylistGroup	Playlist-group (exhibition)
ParseAndValidateRefManifest	Ref manifest
ParseAndValidateChannel	channels extension document

import "github.com/display-protocol/dp1-go"

p, err := dp1.ParseAndValidatePlaylist(playlistJSON)
if err != nil {
    return err
}

g, err := dp1.ParseAndValidatePlaylistGroup(groupJSON)
m, err := dp1.ParseAndValidateRefManifest(manifestJSON)
ch, err := dp1.ParseAndValidateChannel(channelJSON)

Playlist with the optional playlists extension overlay:

p, err := dp1.ParseAndValidatePlaylistWithPlaylistsExtension(data)

Errors

• errors.Is(err, dp1.ErrValidation) — JSON Schema validation failed (after mapping, playlist failures still wrap ErrValidation).
• errors.As into *dp1.CodedError — stable ErrorCode for UI/telemetry (e.g. dp1.CodePlaylistInvalid; dp1.CodeSigInvalid is used by the sign package). Validation failures use codes such as CodePlaylistInvalid, CodePlaylistGroupInvalid, CodeRefManifestInvalid, CodeChannelInvalid.

var coded *dp1.CodedError
if errors.As(err, &coded) {
    _ = coded.Code
}

dpVersion (DP-1 §12)

v, err := dp1.ParseDPVersion(p.DPVersion)
if err != nil { /* ... */ }
_ = dp1.WarnMajorMismatch(v, 1) // optional: warn if document major ≠ player major

Signing (github.com/display-protocol/dp1-go/sign)

• sign.PayloadHashString / sign.VerifyPayloadHash — sha256:<hex> for payload_hash (DP-1 §7.1: strip top-level signature fields, JCS, trailing LF, then SHA-256).
• sign.SignLegacyEd25519 / sign.VerifyLegacyEd25519 — v1.0.x signature: ed25519:<hex> over that same digest.
• sign.Ed25519DIDKey / sign.Ed25519PublicKeyFromDIDKey — encode and decode did:key for a raw Ed25519 public key (W3C did🔑 multicodec ed25519-pub + multibase base58btc). VerifyMultiEd25519 accepts only this kid form.
• sign.SignMultiEd25519 / sign.VerifyMultiEd25519 — v1.1+ signatures[]: Ed25519 signs the same 32-byte digest; SignMultiEd25519 sets kid via Ed25519DIDKey; payload_hash is checked separately. Ed25519 only for now.
• sign.VerifyMultiSignaturesJSON — decodes the top-level signatures array from raw JSON and verifies each entry (same rules as VerifyMultiEd25519); shared by playlist, playlist-group, and channel documents. sign.VerifyPlaylistSignatures, sign.VerifyPlaylistGroupSignatures, and sign.VerifyChannelSignatures are equivalent wrappers for clarity. Returns an error if JSON is invalid, signatures is missing or empty (ErrNoSignatures), or a signature entry cannot decode; otherwise ok plus failed playlist.Signature values (in order). Non-Ed25519 algorithms count as failures.

Display merge (github.com/display-protocol/dp1-go/merge)

Resolution order: defaults → ref manifest controls → item override → item-local display fields.

import "github.com/display-protocol/dp1-go/merge"

prefs, err := merge.DisplayForItem(def, refManifest, item)

Extension types (optional)

Shared and extension-specific structs live under extension/ (for example extension/playlists for the playlists overlay, extension/identity for Entity, extension/channels for the channel document type). Prefer ParseAndValidate* at the root package for full schema validation.

Schemas

Normative JSON Schemas are embedded from the spec repo under internal/schema/ (core v1.1.0 + extensions + a small overlay for playlist + playlists-extension allOf).

Testing

go test ./... -race -count=1
bash scripts/check-coverage.sh 80   # merged module coverage threshold (CI)

CI uploads the merged profile to Codecov after the threshold check. If uploads require authentication, add a CODECOV_TOKEN repository secret from codecov.io.

License

See LICENSE.

Documentation

Overview

Package dp1 implements parsing, validation, and helpers for the DP-1 protocol (playlists, playlist-groups, ref manifests, and registered extensions).

Entrypoints use JSON Schema (draft 2020-12) embedded from the specification: use ParseAndValidate* functions to obtain typed values that are known to match the schema.

Index

• Variables
• func CodeFromChannelValidation(err error) error
• func CodeFromPlaylistGroupValidation(err error) error
• func CodeFromPlaylistValidation(err error) error
• func CodeFromRefManifestValidation(err error) error
• func ParseAndValidateChannel(data []byte) (*channels.Channel, error)
• func ParseAndValidatePlaylist(data []byte) (*playlist.Playlist, error)
• func ParseAndValidatePlaylistGroup(data []byte) (*playlistgroup.Group, error)
• func ParseAndValidatePlaylistWithPlaylistsExtension(data []byte) (*playlist.Playlist, error)
• func ParseAndValidateRefManifest(data []byte) (*refmanifest.Manifest, error)
• func ParseDPVersion(s string) (*semver.Version, error)
• func WarnMajorMismatch(document *semver.Version, wantMajor uint64) error
• func WithCode(code ErrorCode, err error) error
• type CodedError
  • func (e *CodedError) Error() string
  • func (e *CodedError) Unwrap() error
• type ErrorCode

Variables

var (
	ErrValidation     = validate.ErrValidation
	ErrSigInvalid     = sign.ErrSigInvalid
	ErrUnsupportedAlg = sign.ErrUnsupportedAlg
	ErrNoSignatures   = sign.ErrNoSignatures
)

Sentinel errors re-exported so applications can use a single import path with errors.Is / errors.As (e.g. signature verification vs JSON Schema validation).

var (
	PlaylistCoreSchemaValidate                   = validate.Playlist
	PlaylistWithPlaylistsExtensionSchemaValidate = validate.PlaylistWithPlaylistsExtension
	PlaylistGroupSchemaValidate                  = validate.PlaylistGroup
	RefManifestSchemaValidate                    = validate.RefManifest
	ChannelExtensionSchemaValidate               = validate.ChannelsExtension
)

The following hooks default to the real JSON Schema validators. Tests may replace them briefly to exercise JSON decode error paths. Do not reassign concurrently in production.

Functions

func CodeFromChannelValidation

func CodeFromChannelValidation(err error) error

CodeFromChannelValidation maps JSON Schema validation failures to CodeChannelInvalid.

func CodeFromPlaylistGroupValidation

func CodeFromPlaylistGroupValidation(err error) error

CodeFromPlaylistGroupValidation maps JSON Schema validation failures to CodePlaylistGroupInvalid.

func CodeFromPlaylistValidation

func CodeFromPlaylistValidation(err error) error

CodeFromPlaylistValidation maps JSON Schema validation failures to CodePlaylistInvalid (playlist core or playlist + playlists extension schemas). The wrapped error still satisfies errors.Is(err, ErrValidation) for the underlying failure.

func CodeFromRefManifestValidation

func CodeFromRefManifestValidation(err error) error

CodeFromRefManifestValidation maps JSON Schema validation failures to CodeRefManifestInvalid.

func ParseAndValidateChannel

func ParseAndValidateChannel(data []byte) (*channels.Channel, error)

ParseAndValidateChannel validates the channels extension document.

func ParseAndValidatePlaylist

func ParseAndValidatePlaylist(data []byte) (*playlist.Playlist, error)

ParseAndValidatePlaylist validates against the core playlist schema and decodes into playlist.Playlist.

func ParseAndValidatePlaylistGroup

func ParseAndValidatePlaylistGroup(data []byte) (*playlistgroup.Group, error)

ParseAndValidatePlaylistGroup validates a playlist-group (exhibition) document.

func ParseAndValidatePlaylistWithPlaylistsExtension

func ParseAndValidatePlaylistWithPlaylistsExtension(data []byte) (*playlist.Playlist, error)

ParseAndValidatePlaylistWithPlaylistsExtension validates core + playlists extension overlay.

func ParseAndValidateRefManifest

func ParseAndValidateRefManifest(data []byte) (*refmanifest.Manifest, error)

ParseAndValidateRefManifest validates a ref manifest document.

func ParseDPVersion

func ParseDPVersion(s string) (*semver.Version, error)

ParseDPVersion parses a document dpVersion field (SemVer), per DP-1 §12. Typical use: after decoding a playlist, compare or log against the player’s supported spec version.

func WarnMajorMismatch

func WarnMajorMismatch(document *semver.Version, wantMajor uint64) error

WarnMajorMismatch is an optional policy helper for §12 (“players warn on major mismatch”). Pass the parsed dpVersion and the major version your player implements (e.g. 1 for DP-1 v1.x). Nil document is a no-op so callers can skip parsing when the field is absent.

func WithCode

func WithCode(code ErrorCode, err error) error

WithCode wraps err when err is non-nil.

Types

type CodedError

type CodedError struct {
	Code ErrorCode
	Err  error
}

CodedError wraps an error with ErrorCode for UI or telemetry.

func (*CodedError) Error

func (e *CodedError) Error() string

func (*CodedError) Unwrap

func (e *CodedError) Unwrap() error

type ErrorCode

type ErrorCode string

ErrorCode is a stable string for DP-1 §14 (player → UI) mapping where applicable, plus SDK-specific codes for document types not named in §14.

const (
	// CodePlaylistInvalid is the §14 code for playlist schema / structural failure (“Playlist malformed.”).
	// Use with ParseAndValidatePlaylist and ParseAndValidatePlaylistWithPlaylistsExtension only.
	CodePlaylistInvalid ErrorCode = "playlistInvalid"
	// CodePlaylistGroupInvalid is used when a playlist-group (exhibition) document fails JSON Schema validation or decode.
	CodePlaylistGroupInvalid ErrorCode = "playlistGroupInvalid"
	// CodeRefManifestInvalid is used when a ref manifest document fails JSON Schema validation or decode.
	CodeRefManifestInvalid ErrorCode = "refManifestInvalid"
	// CodeChannelInvalid is used when a channel extension document fails JSON Schema validation or decode.
	CodeChannelInvalid ErrorCode = "channelInvalid"
	// CodeSigInvalid is the §14 code for signature verification failure (“Invalid feed signature.”).
	// Returned by the sign package; not emitted from ParseAndValidate* helpers.
	CodeSigInvalid ErrorCode = "sigInvalid"
	// The following §14 codes are reserved for player/runtime behavior (auth, hash drift, network).
	// This parsing/signing SDK does not emit them; clients may use them when implementing a full player.
	CodeLicenseDenied     ErrorCode = "licenseDenied"
	CodeReproMismatch     ErrorCode = "reproMismatch"
	CodeSourceUnreachable ErrorCode = "sourceUnreachable"
)