lexicon

Documentation

Overview

Package lexicon parses ATProto Lexicon JSON schema files.

Index

• func SplitRef(currentNSID, ref string) (nsid, defName string)
• type Body
• type Catalog
  • func NewCatalog() *Catalog
  • func (c *Catalog) Add(s *Schema) error
  • func (c *Catalog) AddAll(schemas []*Schema) error
  • func (c *Catalog) Resolve() error
  • func (c *Catalog) Schema(nsid string) *Schema
  • func (c *Catalog) Schemas() []*Schema
• type Def
• type ErrorDef
• type Field
• type Message
• type Object
• type Params
• type Schema
  • func Parse(data []byte) (*Schema, error)
  • func ParseDir(dir string) ([]*Schema, error)
  • func ParseFile(path string) (*Schema, error)

Functions

func SplitRef

func SplitRef(currentNSID, ref string) (nsid, defName string)

SplitRef resolves a reference string relative to the given schema NSID. Returns the target NSID and def name.

"#replyRef"                        → (currentNSID, "replyRef")
"com.atproto.repo.defs#commitMeta" → ("com.atproto.repo.defs", "commitMeta")
"com.atproto.repo.strongRef"       → ("com.atproto.repo.strongRef", "main")

Types

type Body

type Body struct {
	Desc     string `json:"description,omitempty"`
	Encoding string `json:"encoding"`
	Schema   *Field `json:"schema,omitempty"`
}

Body describes a request or response body.

type Catalog

type Catalog struct {
	// contains filtered or unexported fields
}

Catalog holds parsed schemas and resolves cross-file references.

func NewCatalog

func NewCatalog() *Catalog

NewCatalog creates an empty catalog.

func (*Catalog) Add

func (c *Catalog) Add(s *Schema) error

Add registers a schema in the catalog. Returns an error if the NSID is already registered.

func (*Catalog) AddAll

func (c *Catalog) AddAll(schemas []*Schema) error

AddAll registers multiple schemas.

func (*Catalog) Resolve

func (c *Catalog) Resolve() error

Resolve validates that all references in all schemas point to existing definitions. Returns an error listing all unresolved references.

func (*Catalog) Schema

func (c *Catalog) Schema(nsid string) *Schema

Schema returns the schema for the given NSID, or nil.

func (*Catalog) Schemas

func (c *Catalog) Schemas() []*Schema

Schemas returns all schemas sorted by NSID.

type Def

type Def struct {
	Type string `json:"type"` // "record", "query", "procedure", "subscription", "object", "string", "token", etc.
	Desc string `json:"description,omitempty"`

	// Record
	Key    string  `json:"key,omitempty"`    // "tid", "nsid", "any", "literal:self"
	Record *Object `json:"record,omitempty"` // the record's object schema

	// Query / Procedure
	Parameters *Params    `json:"parameters,omitempty"`
	Input      *Body      `json:"input,omitempty"`
	Output     *Body      `json:"output,omitempty"`
	Errors     []ErrorDef `json:"errors,omitempty"`

	// Subscription
	Message *Message `json:"message,omitempty"`

	// Inline object fields (when Type is "object")
	Properties map[string]*Field `json:"properties,omitempty"`
	Required   []string          `json:"required,omitempty"`
	Nullable   []string          `json:"nullable,omitempty"`

	// Inline string fields (when Type is "string")
	Format       string   `json:"format,omitempty"`
	MaxLength    int      `json:"maxLength,omitempty"`
	MinLength    int      `json:"minLength,omitempty"`
	MaxGraphemes int      `json:"maxGraphemes,omitempty"`
	MinGraphemes int      `json:"minGraphemes,omitempty"`
	Enum         []string `json:"enum,omitempty"`
	KnownValues  []string `json:"knownValues,omitempty"`
	Default      any      `json:"default,omitempty"`
	Const        any      `json:"const,omitempty"`

	// Inline integer fields (when Type is "integer")
	Minimum *int64 `json:"minimum,omitempty"`
	Maximum *int64 `json:"maximum,omitempty"`

	// Inline array fields (when Type is "array")
	Items *Field `json:"items,omitempty"`

	// Inline union fields (when Type is "union")
	Refs   []string `json:"refs,omitempty"`
	Closed bool     `json:"closed,omitempty"`

	// Inline ref field (when Type is "ref")
	Ref string `json:"ref,omitempty"`
}

Def is a single named definition within a schema.

type ErrorDef

type ErrorDef struct {
	Name string `json:"name"`
	Desc string `json:"description,omitempty"`
}

ErrorDef describes a named error that an endpoint can return.

type Field

type Field struct {
	Type string `json:"type"` // "string", "integer", "boolean", "bytes", "cid-link", "blob", "array", "object", "ref", "union", "unknown", "null"
	Desc string `json:"description,omitempty"`

	// String / Array / Bytes constraints (maxLength means bytes for string, elements for array)
	Format       string   `json:"format,omitempty"`
	MaxLength    int      `json:"maxLength,omitempty"`
	MinLength    int      `json:"minLength,omitempty"`
	MaxGraphemes int      `json:"maxGraphemes,omitempty"`
	MinGraphemes int      `json:"minGraphemes,omitempty"`
	Enum         []string `json:"enum,omitempty"`
	KnownValues  []string `json:"knownValues,omitempty"`
	Default      any      `json:"default,omitempty"`
	Const        any      `json:"const,omitempty"`

	// Integer constraints
	Minimum *int64 `json:"minimum,omitempty"`
	Maximum *int64 `json:"maximum,omitempty"`

	// Array items
	Items *Field `json:"items,omitempty"`

	// Ref
	Ref string `json:"ref,omitempty"`

	// Union
	Refs   []string `json:"refs,omitempty"`
	Closed bool     `json:"closed,omitempty"`

	// Blob
	Accept  []string `json:"accept,omitempty"`
	MaxSize int64    `json:"maxSize,omitempty"`

	// Nested object
	Properties map[string]*Field `json:"properties,omitempty"`
	Required   []string          `json:"required,omitempty"`
	Nullable   []string          `json:"nullable,omitempty"`
}

Field describes a single field within an object or array items. Constraints are shared across types that use them (e.g. maxLength applies to strings as byte length and to arrays as element count).

type Message

type Message struct {
	Desc   string `json:"description,omitempty"`
	Schema *Field `json:"schema,omitempty"`
}

Message describes a subscription message.

type Object

type Object struct {
	Type       string            `json:"type"` // always "object"
	Desc       string            `json:"description,omitempty"`
	Properties map[string]*Field `json:"properties,omitempty"`
	Required   []string          `json:"required,omitempty"`
	Nullable   []string          `json:"nullable,omitempty"`
}

Object describes a lexicon object type with named properties.

type Params

type Params struct {
	Type       string            `json:"type"` // always "params"
	Properties map[string]*Field `json:"properties,omitempty"`
	Required   []string          `json:"required,omitempty"`
}

Params describes query/procedure parameters (restricted to primitives).

type Schema

type Schema struct {
	Lexicon int             `json:"lexicon"` // always 1
	ID      string          `json:"id"`      // NSID, e.g. "app.bsky.feed.post"
	Desc    string          `json:"description,omitempty"`
	Defs    map[string]*Def `json:"defs"`
}

Schema is a parsed lexicon document.

func Parse

func Parse(data []byte) (*Schema, error)

Parse parses a lexicon JSON document.

func ParseDir

func ParseDir(dir string) ([]*Schema, error)

ParseDir recursively finds and parses all .json lexicon files under dir.

func ParseFile

func ParseFile(path string) (*Schema, error)

ParseFile reads and parses a single lexicon JSON file.