lexicon

package
v0.0.0-...-adf259e Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 26, 2025 License: Apache-2.0, MIT Imports: 17 Imported by: 0

Documentation

Overview

Package atproto/lexicon provides generic Lexicon schema parsing and run-time validation.

Index

Examples

Constants

View Source 
const (
	// Flag which allows legacy "blob" data to pass validation.
	AllowLegacyBlob = 1 << iota
	// Flag which loosens "datetime" string syntax validation. String must still be an ISO datetime, but might be missing timezone (for example)
	AllowLenientDatetime
	// Flag which requires validation of nested data in open unions. By default nested union types are only validated optimistically (if the type is known in catatalog) for unlisted types. This flag will result in a validation error if the Lexicon can't be resolved from the catalog.
	StrictRecursiveValidation
)

Variables

This section is empty.

Functions

func ExtractTypeJSON 

func ExtractTypeJSON(b []byte) (string, error)

Parses the top-level $type field from generic atproto JSON data

func ResolveLexiconData 

func ResolveLexiconData(ctx context.Context, dir identity.Directory, nsid syntax.NSID) (map[string]any, error)

Low-level routine for resolving an NSID to full Lexicon data record (as stored in a repository).

The current implementation uses a naive 'getRepo' fetch to the relevant PDS instance, without validating MST proof chain.

Calling code should usually use ResolvingCatalog, which handles basic caching and validation of the Lexicon language itself.

func ValidateRecord 

func ValidateRecord(cat Catalog, recordData any, ref string, flags ValidateFlags) error

Checks Lexicon schema (fetched from the catalog) for the given record, with optional flags tweaking default validation rules.

'recordData' is typed as 'any', but is expected to be 'map[string]any' 'ref' is a reference to the schema type, as an NSID with optional fragment. For records, the '$type' must match 'ref' 'flags' are parameters tweaking Lexicon validation rules. Zero value is default.

Example 
// First load Lexicon schema JSON files from local disk.
cat := NewBaseCatalog()
if err := cat.LoadDirectory("testdata/catalog"); err != nil {
	panic("failed to load lexicons")
}

// Parse record JSON data using atproto/data helper
recordJSON := `{
		"$type": "example.lexicon.record",
		"integer": 123,
        "formats": {
            "did": "did:web:example.com",
            "aturi": "at://handle.example.com/com.example.nsid/asdf123",
            "datetime": "2023-10-30T22:25:23Z",
            "language": "en",
            "tid": "3kznmn7xqxl22"
        }
	}`

recordData, err := atdata.UnmarshalJSON([]byte(recordJSON))
if err != nil {
	panic("failed to parse record JSON")
}

if err := ValidateRecord(&cat, recordData, "example.lexicon.record", 0); err != nil {
	fmt.Printf("Schema validation failed: %v\n", err)
} else {
	fmt.Println("Success!")
}

Output:

Success!

Types

type BaseCatalog 

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

Trivial in-memory Lexicon Catalog implementation.

func NewBaseCatalog 

func NewBaseCatalog() BaseCatalog

Creates a new empty BaseCatalog

func (*BaseCatalog) AddSchemaFile 

func (c *BaseCatalog) AddSchemaFile(sf SchemaFile) error

Inserts a schema loaded from a JSON file in to the catalog.

func (*BaseCatalog) LoadDirectory 

func (c *BaseCatalog) LoadDirectory(dirPath string) error

Recursively loads all '.json' files from a directory in to the catalog.

func (*BaseCatalog) LoadEmbedFS 

func (c *BaseCatalog) LoadEmbedFS(efs embed.FS) error

Recursively loads all '.json' files from an embed.FS

func (*BaseCatalog) Resolve 

func (c *BaseCatalog) Resolve(ref string) (*Schema, error)

Returns a scheman definition (`Schema` struct) for a Lexicon reference.

A Lexicon ref string is an NSID with an optional #-separated fragment. If the fragment isn't specified, '#main' is used by default.

type Catalog 

type Catalog interface {
	// Looks up a schema refrence (NSID string with optional fragment) to a Schema object.
	Resolve(ref string) (*Schema, error)
}

Interface type for a resolver or container of lexicon schemas, and methods for validating generic data against those schemas.

type ResolvingCatalog 

type ResolvingCatalog struct {
	Base      BaseCatalog
	Directory identity.Directory
}

Catalog which supplements an in-memory BaseCatalog with live resolution from the network

func NewResolvingCatalog 

func NewResolvingCatalog() ResolvingCatalog

func (*ResolvingCatalog) Resolve 

func (rc *ResolvingCatalog) Resolve(ref string) (*Schema, error)

type Schema 

type Schema struct {
	ID  string
	Def any
}

Represents a Lexicon schema definition

type SchemaArray 

type SchemaArray struct {
	Type        string    `json:"type,const=array"`
	Description *string   `json:"description,omitempty"`
	Items       SchemaDef `json:"items"`
	MinLength   *int      `json:"minLength,omitempty"`
	MaxLength   *int      `json:"maxLength,omitempty"`
}

func (*SchemaArray) CheckSchema 

func (s *SchemaArray) CheckSchema() error

type SchemaBlob 

type SchemaBlob struct {
	Type        string   `json:"type,const=blob"`
	Description *string  `json:"description,omitempty"`
	Accept      []string `json:"accept,omitempty"`
	MaxSize     *int     `json:"maxSize,omitempty"`
}

func (*SchemaBlob) CheckSchema 

func (s *SchemaBlob) CheckSchema() error

func (*SchemaBlob) Validate 

func (s *SchemaBlob) Validate(d any, flags ValidateFlags) error

type SchemaBody 

type SchemaBody struct {
	Description *string    `json:"description,omitempty"`
	Encoding    string     `json:"encoding"` // required, mimetype
	Schema      *SchemaDef `json:"schema"`   // optional; type:object, type:ref, or type:union
}

func (*SchemaBody) CheckSchema 

func (s *SchemaBody) CheckSchema() error

type SchemaBoolean 

type SchemaBoolean struct {
	Type        string  `json:"type,const=bool"`
	Description *string `json:"description,omitempty"`
	Default     *bool   `json:"default,omitempty"`
	Const       *bool   `json:"const,omitempty"`
}

func (*SchemaBoolean) CheckSchema 

func (s *SchemaBoolean) CheckSchema() error

func (*SchemaBoolean) Validate 

func (s *SchemaBoolean) Validate(d any) error

type SchemaBytes 

type SchemaBytes struct {
	Type        string  `json:"type,const=bytes"`
	Description *string `json:"description,omitempty"`
	MinLength   *int    `json:"minLength,omitempty"`
	MaxLength   *int    `json:"maxLength,omitempty"`
}

func (*SchemaBytes) CheckSchema 

func (s *SchemaBytes) CheckSchema() error

func (*SchemaBytes) Validate 

func (s *SchemaBytes) Validate(d any) error
type SchemaCIDLink struct {
	Type        string  `json:"type,const=cid-link"`
	Description *string `json:"description,omitempty"`
}

func (*SchemaCIDLink) CheckSchema 

func (s *SchemaCIDLink) CheckSchema() error

func (*SchemaCIDLink) Validate 

func (s *SchemaCIDLink) Validate(d any) error

type SchemaDef 

type SchemaDef struct {
	Inner any
}

enum type to represent any of the schema fields

func (*SchemaDef) CheckSchema 

func (s *SchemaDef) CheckSchema() error

Checks that the schema definition itself is valid (recursively).

func (SchemaDef) MarshalJSON 

func (s SchemaDef) MarshalJSON() ([]byte, error)

func (*SchemaDef) SetBase 

func (s *SchemaDef) SetBase(base string)

Helper to recurse down the definition tree and set full references on any sub-schemas which need to embed that metadata

func (*SchemaDef) UnmarshalJSON 

func (s *SchemaDef) UnmarshalJSON(b []byte) error

type SchemaError 

type SchemaError struct {
	Name        string  `json:"name"`
	Description *string `json:"description"`
}

func (*SchemaError) CheckSchema 

func (s *SchemaError) CheckSchema() error

func (*SchemaError) Validate 

func (s *SchemaError) Validate(d any) error

type SchemaFile 

type SchemaFile struct {
	Lexicon     int                  `json:"lexicon,const=1"`
	ID          string               `json:"id"`
	Description *string              `json:"description,omitempty"`
	Defs        map[string]SchemaDef `json:"defs"`
}

Serialization helper type for top-level Lexicon schema JSON objects (files)

func ResolveLexiconSchemaFile 

func ResolveLexiconSchemaFile(ctx context.Context, dir identity.Directory, nsid syntax.NSID) (*SchemaFile, error)

Low-level routine for resolving an NSID to `SchemaFile`.

Same as `ResolveLexiconData`, but returns a parsed `SchemaFile` struct.

type SchemaInteger 

type SchemaInteger struct {
	Type        string  `json:"type,const=integer"`
	Description *string `json:"description,omitempty"`
	Minimum     *int    `json:"minimum,omitempty"`
	Maximum     *int    `json:"maximum,omitempty"`
	Enum        []int   `json:"enum,omitempty"`
	Default     *int    `json:"default,omitempty"`
	Const       *int    `json:"const,omitempty"`
}

func (*SchemaInteger) CheckSchema 

func (s *SchemaInteger) CheckSchema() error

func (*SchemaInteger) Validate 

func (s *SchemaInteger) Validate(d any) error

type SchemaMessage 

type SchemaMessage struct {
	Description *string   `json:"description,omitempty"`
	Schema      SchemaDef `json:"schema"` // required; type:union only
}

func (*SchemaMessage) CheckSchema 

func (s *SchemaMessage) CheckSchema() error

type SchemaNull 

type SchemaNull struct {
	Type        string  `json:"type,const=null"`
	Description *string `json:"description,omitempty"`
}

func (*SchemaNull) CheckSchema 

func (s *SchemaNull) CheckSchema() error

func (*SchemaNull) Validate 

func (s *SchemaNull) Validate(d any) error

type SchemaObject 

type SchemaObject struct {
	Type        string               `json:"type,const=object"`
	Description *string              `json:"description,omitempty"`
	Properties  map[string]SchemaDef `json:"properties"`
	Required    []string             `json:"required,omitempty"`
	Nullable    []string             `json:"nullable,omitempty"`
}

func (*SchemaObject) CheckSchema 

func (s *SchemaObject) CheckSchema() error

func (*SchemaObject) IsNullable 

func (s *SchemaObject) IsNullable(k string) bool

Checks if a field name 'k' is one of the Nullable fields for this object

type SchemaParams 

type SchemaParams struct {
	Type        string               `json:"type,const=params"`
	Description *string              `json:"description,omitempty"`
	Properties  map[string]SchemaDef `json:"properties"` // boolean, integer, string, or unknown; or an array of these types
	Required    []string             `json:"required,omitempty"`
}

func (*SchemaParams) CheckSchema 

func (s *SchemaParams) CheckSchema() error

type SchemaProcedure 

type SchemaProcedure struct {
	Type        string        `json:"type,const=procedure"`
	Description *string       `json:"description,omitempty"`
	Parameters  SchemaParams  `json:"parameters"`
	Output      *SchemaBody   `json:"output"`           // optional
	Errors      []SchemaError `json:"errors,omitempty"` // optional
	Input       *SchemaBody   `json:"input"`            // optional
}

func (*SchemaProcedure) CheckSchema 

func (s *SchemaProcedure) CheckSchema() error

type SchemaQuery 

type SchemaQuery struct {
	Type        string        `json:"type,const=query"`
	Description *string       `json:"description,omitempty"`
	Parameters  SchemaParams  `json:"parameters"`
	Output      *SchemaBody   `json:"output"`
	Errors      []SchemaError `json:"errors,omitempty"` // optional
}

func (*SchemaQuery) CheckSchema 

func (s *SchemaQuery) CheckSchema() error

type SchemaRecord 

type SchemaRecord struct {
	Type        string       `json:"type,const=record"`
	Description *string      `json:"description,omitempty"`
	Key         string       `json:"key"`
	Record      SchemaObject `json:"record"`
}

func (*SchemaRecord) CheckSchema 

func (s *SchemaRecord) CheckSchema() error

type SchemaRef 

type SchemaRef struct {
	Type        string  `json:"type,const=ref"`
	Description *string `json:"description,omitempty"`
	Ref         string  `json:"ref"`
	// contains filtered or unexported fields
}

func (*SchemaRef) CheckSchema 

func (s *SchemaRef) CheckSchema() error

type SchemaString 

type SchemaString struct {
	Type         string   `json:"type,const=string"`
	Description  *string  `json:"description,omitempty"`
	Format       *string  `json:"format,omitempty"`
	MinLength    *int     `json:"minLength,omitempty"`
	MaxLength    *int     `json:"maxLength,omitempty"`
	MinGraphemes *int     `json:"minGraphemes,omitempty"`
	MaxGraphemes *int     `json:"maxGraphemes,omitempty"`
	KnownValues  []string `json:"knownValues,omitempty"`
	Enum         []string `json:"enum,omitempty"`
	Default      *string  `json:"default,omitempty"`
	Const        *string  `json:"const,omitempty"`
}

func (*SchemaString) CheckSchema 

func (s *SchemaString) CheckSchema() error

func (*SchemaString) Validate 

func (s *SchemaString) Validate(d any, flags ValidateFlags) error

type SchemaSubscription 

type SchemaSubscription struct {
	Type        string         `json:"type,const=subscription"`
	Description *string        `json:"description,omitempty"`
	Parameters  SchemaParams   `json:"parameters"`
	Message     *SchemaMessage `json:"message,omitempty"` // TODO(specs): is this really optional?
}

func (*SchemaSubscription) CheckSchema 

func (s *SchemaSubscription) CheckSchema() error

type SchemaToken 

type SchemaToken struct {
	Type        string  `json:"type,const=token"`
	Description *string `json:"description,omitempty"`
	// contains filtered or unexported fields
}

func (*SchemaToken) CheckSchema 

func (s *SchemaToken) CheckSchema() error

func (*SchemaToken) Validate 

func (s *SchemaToken) Validate(d any) error

type SchemaUnion 

type SchemaUnion struct {
	Type        string   `json:"type,const=union"`
	Description *string  `json:"description,omitempty"`
	Refs        []string `json:"refs"`
	Closed      *bool    `json:"closed,omitempty"`
	// contains filtered or unexported fields
}

func (*SchemaUnion) CheckSchema 

func (s *SchemaUnion) CheckSchema() error

type SchemaUnknown 

type SchemaUnknown struct {
	Type        string  `json:"type,const=unknown"`
	Description *string `json:"description,omitempty"`
}

func (*SchemaUnknown) CheckSchema 

func (s *SchemaUnknown) CheckSchema() error

func (*SchemaUnknown) Validate 

func (s *SchemaUnknown) Validate(d any) error

type ValidateFlags 

type ValidateFlags int

Boolean flags tweaking how Lexicon validation rules are interpreted. 

var LenientMode ValidateFlags = AllowLegacyBlob | AllowLenientDatetime

Combination of agument flags for less formal validation. Recommended for, eg, working with old/legacy data from 2023.

Source Files

View all Source files

Directories

Path Synopsis
cmd
lextool

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.