Schema Contract

The JSON schema contract returned by the server codegen endpoint — schema_version, identity, projects, node_types, and project_node_types — annotated field by field.

The schema contract is the JSON document that drives optixlog generate. The CLI fetches it from the v0.codegen.schema endpoint (or loads it from a local fixture via --fixture) and passes it through contract.py, which validates it into a SchemaContract object before emitting the typed Python module.

Understanding the contract lets you write correct fixture files for offline testing and predict exactly what code will be generated from a given schema.

Full sample

The file at python-sdk-spec/tests/fixtures/schema.sample.json is the canonical example used in all offline tests. It is reproduced here with all three node types and the many-to-many project mapping:

schema.sample.json

{
  "schema_version": 1,
  "identity": {
    "key_type": "service",
    "organization_id": "org_leidos_01",
    "user_email": "founder@optixlog.com",
    "scoped_project_ids": ["proj_grating_7f3a", "proj_modulator_22b1"]
  },
  "projects": [
    { "id": "proj_grating_7f3a", "name": "Grating Coupler Lab" },
    { "id": "proj_modulator_22b1", "name": "Modulator Program" }
  ],
  "node_types": [
    {
      "name": "SimulationNode",
      "fields": [
        { "name": "config",        "type": "json",                            "required": true  },
        { "name": "solver",        "type": "enum", "enum": ["fdtd","eme","varfdtd"], "required": true  },
        { "name": "wavelength_nm", "type": "number",                          "required": false, "default": 1550.0 },
        { "name": "other_param",   "type": "string",                          "required": false }
      ]
    },
    {
      "name": "MeasurementNode",
      "fields": [
        { "name": "instrument", "type": "string",        "required": true  },
        { "name": "samples",    "type": "array<number>", "required": true  },
        { "name": "notes",      "type": "string",        "required": false }
      ]
    },
    {
      "name": "LayoutNode",
      "fields": [
        { "name": "gds_path",  "type": "string", "required": true  },
        { "name": "layer_map", "type": "json",   "required": false }
      ]
    }
  ],
  "project_node_types": {
    "proj_grating_7f3a":   ["SimulationNode", "MeasurementNode"],
    "proj_modulator_22b1": ["SimulationNode", "LayoutNode"]
  }
}

Top-level fields

`schema_version`

Type: integer — required

The version of the contract format. Only 1 is currently supported. Passing any other value raises ContractError and aborts generation.

`identity`

Type: object — optional

Carries metadata about the API key that was used to fetch the schema. This information is used for diagnostics and is displayed during optixlog login and optixlog whoami. It does not affect the generated code.

Field	Type	Default	Description
`key_type`	`string`	`"unknown"`	`"service"` or `"user"` (the server may report `"human"`, displayed as `"user"`).
`organization_id`	`string \| null`	`null`	Stable id of the owning organization.
`user_email`	`string \| null`	`null`	Email of the authenticated user (user keys only).
`scoped_project_ids`	`string[]`	`[]`	Project ids the key has permission to access.

`projects`

Type: object[] — required

One entry per project. The list order is preserved in the generated Projects constants and in the order of OptixClient.project() overloads.

Field	Type	Description
`id`	`string`	Stable project identifier (e.g. `"proj_grating_7f3a"`). Becomes the `Literal` value in the generated overloads and the `_PROJECT_WRAPPERS` key. Duplicate ids are rejected with `ContractError`.
`name`	`string`	Human-readable label (e.g. `"Grating Coupler Lab"`). Converted to `UPPER_SNAKE_CASE` to form the `Projects` constant name.

name vs projectName

The contract parser accepts either name or projectName for the project display name. The Neo4j backend may return the field as projectName; both are normalized to name internally.

`node_types`

Type: object[] — required

One entry per node type, deduplicated by name. Each entry defines a dataclass that will appear in the generated module.

Field	Type	Description
`name`	`string`	Node type name in PascalCase (e.g. `"SimulationNode"`). Becomes the dataclass name verbatim.
`fields`	`object[]`	The typed fields for this node (may be empty).

Field objects

Each element of fields has the following shape:

Field	Type	Required	Description
`name`	`string`	yes	Field/attribute name. Duplicate field names within a node are rejected.
`type`	`string`	yes	One of the supported contract types (see Type Mapping).
`required`	`boolean`	no (default `false`)	Whether the field must be supplied.
`default`	`any`	no	The default value. Presence is significant: `"default": null` is a real default of `None`, distinct from omitting the key entirely.
`enum`	`string[]`	only when `type == "enum"`	The allowed literal values. An `enum` type with no `enum` array raises `TypeMapError`.

Conflicting node definitions

If the same node type name appears in node_types more than once and the two definitions have different fields, ContractError is raised. An exact re-declaration (identical fields) is silently de-duplicated. This matters when writing hand-crafted fixtures — ensure shared node types have identical field lists across any duplication.

`project_node_types`

Type: object — required

The many-to-many mapping from project id to the list of node type names available in that project. This is the only place the node↔project association lives. It is never stored in optixlog.toml and is re-fetched at every optixlog generate run.

"project_node_types": {
  "proj_grating_7f3a":   ["SimulationNode", "MeasurementNode"],
  "proj_modulator_22b1": ["SimulationNode", "LayoutNode"]
}

Rules enforced by contract.py:

Every key must be a project id present in projects. Unknown keys raise ContractError.
Every value name must be a node type name present in node_types. Unknown names raise ContractError.
A project listed here with an empty array is rejected — there is nothing to generate for it.
A node type may appear under multiple projects (many-to-many). It is emitted as a single dataclass that joins each project's union alias.

Using a fixture offline

You can use any valid schema contract JSON as a fixture. Pass it to any CLI command with --fixture or set OPTIXLOG_FIXTURE:

optixlog login    --fixture path/to/schema.json --api-key sk-opt-test --base-url http://localhost
optixlog init     --fixture path/to/schema.json --all
optixlog generate --fixture path/to/schema.json

See Offline Fixture Workflow for the full walkthrough.

Schema Contract

On this page