Adding a schema codec
A schema codec speaks one version of the System One API. Adding one, for
example a new release of the standard as systemone/0.3, touches no caller:
configuration resolves schema through the registry, and the Router's client
and listener paths go through the codec interfaces.
- Describe the specification. Add its file under
config/schemas/systemoneand list it in that directory's README. For the standard, write our own description of the interface (field names, types and structure, in our own words), withsourceand thesource_sha256you checked it against; never copy a document that carries no license. Runmake systemone-schemas-driftto compare the description with the published document. - Regenerate the tables.
make systemone-schemas-generaterecords the file and its sha256 inpkg/systemonecodec/zz_generated_specs.go; the registry refuses a codec whose specification does not match. - Write the codec in
src/semantic-router/pkg/systemonecodec: a stateless type withID,Spec,Capabilities,Plan,DecodeReply,ListingPathandDecodeListing.Plandecides every wire call of a batch, one batch call or one call per request; read and write only the IR (systemoneprotocol), never another codec's wire form. A schema a listener may serve also gets aListenerCodec(seelistener.go). - Register it in
Builtin()(registry.go) and add its ID to thesystemoneentry ofpkg/apiregistry(upstream schemas, andListenerSchemaswhen a listener may serve it). - Test it: golden plans and replies, the refusals at load, its errors and listing, and the conformance tests against a mock server built from the specification.
- Document it: the System One schemas page and the compatibility matrix, which is generated from the specifications.