mailschema

README

MailSchema for Go

Decode typed Mail Action Protocol documents and use the canonical MailSchema JSON Schemas in Go.

Specification · Registry · Tools · Source

Install

go get github.com/mailschema/go@v0.1.1

Decode and check a request

package main

import (
	"os"

	mailschema "github.com/mailschema/go"
)

func main() {
	request, err := mailschema.Decode[mailschema.Request](os.Stdin)
	if err != nil {
		panic(err)
	}
	if err := mailschema.ValidateRequest(request); err != nil {
		panic(err)
	}
}

Description, Request, Result and Problem model MAP 0.1 documents. ValidateDescription, ValidateRequest, ValidateResult and ValidateProblem check the fixed profile identifiers and core references while decoding rejects unknown fields and trailing JSON.

Use the schemas

schema, err := mailschema.Schema(mailschema.MAP01Schema)
if err != nil {
	panic(err)
}

MAP01Schema, ContentReview01Schema, ContentReview02Schema and ContributionSchema expose independent copies of the bundled Draft 2020-12 schemas. Use them with a Draft 2020-12 validator when complete schema validation is required.

ContentReview01Contract() and ContentReview02Contract() return immutable canonical type contracts. New integrations should use Content Review 0.2.

Trust boundary

A valid document is structured input. Decoding and validation do not authenticate a service, grant authority, approve an action or establish product conformance. Implementations must apply their own endpoint trust, credentials, permissions and policy before executing a request.

The package performs no network requests. Module versions and MAP profile versions advance independently. MIT licensed.

Documentation

Index

• Constants
• func ContentReview01Contract() []byte
• func ContentReview02Contract() []byte
• func Decode[T any](reader io.Reader) (T, error)
• func Schema(name SchemaName) ([]byte, error)
• func ValidateDescription(value Description) error
• func ValidateProblem(value Problem) error
• func ValidateRequest(value Request) error
• func ValidateResult(value Result) error
• type Authorization
• type Description
• type Execution
• type Operation
• type Problem
• type Request
• type Result
• type SchemaName
• type Service
• type Target
• type TypeReference

Constants

const (
	Profile01         = "https://mailschema.org/profiles/map/0.1"
	Context01         = "https://mailschema.org/contexts/map-0.1.jsonld"
	ContentReviewType = "https://mailschema.org/types/content-review"
)

Functions

func ContentReview01Contract

func ContentReview01Contract() []byte

ContentReview01Contract returns an independent copy of the canonical type contract.

func ContentReview02Contract

func ContentReview02Contract() []byte

ContentReview02Contract returns an independent copy of the current canonical type contract.

func Decode

func Decode[T any](reader io.Reader) (T, error)

Decode reads one strict JSON document. Unknown fields and trailing values are rejected.

func Schema

func Schema(name SchemaName) ([]byte, error)

Schema returns an independent copy of a bundled JSON Schema document.

func ValidateDescription

func ValidateDescription(value Description) error

ValidateDescription checks the fixed MAP 0.1 identifiers and core trust-relevant fields. Use the bundled JSON Schema for complete structural validation.

func ValidateProblem

func ValidateProblem(value Problem) error

ValidateProblem checks a MAP 0.1 problem's fixed identifiers and the required relationship between its code, type URI and HTTP status.

func ValidateRequest

func ValidateRequest(value Request) error

ValidateRequest checks a MAP 0.1 request's fixed identifiers and references. Type-specific input constraints remain in the type schema.

func ValidateResult

func ValidateResult(value Result) error

ValidateResult checks a MAP 0.1 result's fixed identifiers and references. Type-specific output constraints remain in the type schema.

Types

type Authorization

type Authorization struct {
	Kind     string   `json:"kind"`
	Schemes  []string `json:"schemes"`
	Audience string   `json:"audience,omitempty"`
}

type Description

type Description struct {
	Context     string        `json:"@context"`
	Kind        string        `json:"@type"`
	ID          string        `json:"@id"`
	Profile     string        `json:"profile"`
	Type        TypeReference `json:"type"`
	DescribedAt time.Time     `json:"describedAt"`
	ExpiresAt   time.Time     `json:"expiresAt"`
	Service     Service       `json:"service"`
	Target      Target        `json:"target"`
	Operations  []Operation   `json:"operations"`
}

type Execution

type Execution struct {
	URL                    string `json:"url"`
	Method                 string `json:"method"`
	RequestMediaType       string `json:"requestMediaType"`
	ResultMediaType        string `json:"resultMediaType"`
	ResultURLTemplate      string `json:"resultUrlTemplate"`
	ResultRetentionSeconds int    `json:"resultRetentionSeconds"`
}

type Operation

type Operation struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description"`
	InputSchema string `json:"inputSchema"`
}

type Problem

type Problem struct {
	Type          string  `json:"type"`
	Title         string  `json:"title"`
	Status        int     `json:"status"`
	Detail        string  `json:"detail"`
	Instance      string  `json:"instance,omitempty"`
	Profile       string  `json:"profile,omitempty"`
	RequestID     string  `json:"requestId,omitempty"`
	InteractionID string  `json:"interactionId,omitempty"`
	Code          string  `json:"code,omitempty"`
	Target        *Target `json:"target,omitempty"`
}

type Request

type Request struct {
	Kind          string         `json:"kind"`
	Profile       string         `json:"profile"`
	RequestID     string         `json:"requestId"`
	InteractionID string         `json:"interactionId"`
	Type          TypeReference  `json:"type"`
	Operation     string         `json:"operation"`
	Target        Target         `json:"target"`
	Input         map[string]any `json:"input"`
}

type Result

type Result struct {
	Kind          string         `json:"kind"`
	Profile       string         `json:"profile"`
	RequestID     string         `json:"requestId"`
	InteractionID string         `json:"interactionId"`
	Type          TypeReference  `json:"type"`
	Operation     string         `json:"operation"`
	State         string         `json:"state"`
	Target        Target         `json:"target"`
	RecordedAt    time.Time      `json:"recordedAt"`
	ResultURL     string         `json:"resultUrl"`
	Output        map[string]any `json:"output"`
}

type SchemaName

type SchemaName string

SchemaName identifies a schema bundled with this module.

const (
	ContributionSchema    SchemaName = "contribution"
	MAP01Schema           SchemaName = "map-0.1"
	ContentReview01Schema SchemaName = "content-review-0.1"
	ContentReview02Schema SchemaName = "content-review-0.2"
)

type Service

type Service struct {
	ID            string        `json:"id"`
	Name          string        `json:"name"`
	Execution     Execution     `json:"execution"`
	HumanURL      string        `json:"humanUrl"`
	Authorization Authorization `json:"authorization"`
}

type Target

type Target struct {
	ID       string `json:"id"`
	Revision string `json:"revision"`
	Title    string `json:"title,omitempty"`
	Digest   string `json:"digest"`
}

type TypeReference

type TypeReference struct {
	ID             string `json:"id"`
	Version        string `json:"version"`
	ContractDigest string `json:"contractDigest"`
}