JSON contracts

One versioned system schema

insonic uses JSON Schema Draft 2020-12 for configuration, import, artifact/metadata interchange, portable catalog snapshots, durable job events, graph queries and speaker-training/model manifests. A system-wide master schema contains a registry of all insonic-owned contracts and selects documents through their kind. Shared definitions provide consistent identifiers, digests, revisions and artifact references. Cueson retains its own immutable upstream subtitle schema; the master recording embeds its validated current document without redefining that format. Its UUID assignments appear only there; external speaker mappings and other contracts carry current document/cue references, without another assignment list. Local packaged upstream schema bytes provide offline validation.

The master and child schemas live in schemas/v<version>/. Every release has the same software, documentation and master-schema version. A document declares schema_version and kind; the registry resolves its exact child contract. Tagged canonical schema IDs identify release resources, and the packaged registry resolves them offline. Schema files carry descriptions and examples for fields and complete documents. The documentation build reads those fields to produce the contract reference below and packages the JSON files beside it.

Compatibility and evolution

Portable workspace backups use the registered workspace-backup contract. Its manifest binds a consistent logical catalog proof to exact current/durable artifact publications, verified copied bytes or explicit original-store dependency, and accepted-evidence graph rebuilding. Structural validation does not substitute for byte hashes, source receipt validation, destination ownership checks or retention lifetime. See backup commands.

Release candidates use the registered release-candidate contract. The manifest records all four Windows/Linux platform/variant packages, corresponding-source and signing dispositions, exact source revision and documentation archives. Release tooling verifies the embedded package inventories, byte hashes and source identity before publication. See release preparation.

Model selection separates revisioned convenience aliases and configured source catalogs from immutable elected identities. Runtime requests expose alias/source CRUD, discovery and resolution; processing/import payloads freeze selected bundle manifests and acquisition dependencies. Optional compatibility metadata augments base manifests without rewriting accepted older digests. Portable catalog records retain alias/source revisions and trained/hosted target distinctions. Structural schema validation complements runtime checks for target ownership, complete bundle compatibility and job fences. See models for executable commands and lifecycle.

Recording replacement is a targeted media election with explicit transcript keep, clear or replace and declared-roster retain or clear policies. Keep requires an applicability assertion and validates known source-clock bounds and selected track/channel compatibility. A retained older managed subtitle can become the validated embedded current document during that same acceptance. Failure preserves previous accepted state. Roster read and edit requests carry independent optimistic revision authority; intentional membership remains distinct from document attribution and training evidence. The runtime request and import rules expose these elections consistently.

Preserve backward and forward compatibility where practical. Prefer additive optional fields, stable meanings, explicit extension containers and migrations over silently changing existing values. Readers validate against the document's declared version and negotiate adapter capabilities. An unknown version is reported clearly; it is not silently interpreted with whichever schema is newest. Keep supported older registries available for imports and migrations. Unsupported features can remain preserved as opaque extension values where the contract permits them.

Compatibility is a priority, not an absolute prohibition on useful change. When a change breaks a consumer or persisted contract, describe the affected fields, supported source versions and migration/recovery path in the changelog and the brief release highlights. Release notes retain the final changelog link. A schema revision alone does not prove compatibility; validation and representative import/export/migration fixtures establish the supported combinations.

Validation and documentation

Speaker-work requests distinguish dataset creation/inspection, elected training, exact speaker-version retrieval, profile CAS updates and matching-only work. Public matching input cannot supply server-frozen recording/model digests or replace the declared roster with a cluster-count hint. Zero score thresholds and ambiguity margins are explicit values. Catalog schema 10 retains schema-9 portable output/profile/checkpoint authority and origin-qualified mappings, and supports synthetic jobs from 1 through 600000 milliseconds; model/dataset manifests validate against their exact child contracts.

The repository checks master registration, matching release identities, schema validity, field descriptions and embedded examples. Every document example must validate both against its child schema and the master. Contract checks also reject malformed identities, contradictory inputs and mismatched kinds/versions. Structural validation is complemented by application checks for source ownership, time bounds, permissions, revision ordering and backend capabilities; JSON Schema cannot prove those relationships by itself.

The generated reference is read-only output. Edit descriptions, examples and field constraints in the authoritative JSON files, then rebuild documentation. The same packaged definitions serve CLI validation, adapter interchange and offline help. Catalog relationships, import behavior and speaker model lineage explain the domain rules around these payloads.

Contract reference

The versioned root of all insonic-owned interchange contracts. Each document identifies its kind and system schema version. Software, documentation and this registry share the same release version. Stable required fields define each operation while documented extension containers support adapter-specific values. Cueson documents retain their separate immutable upstream schema rather than being rewritten as an insonic format.

Download the master schema · Download shared definitions

The following definitions, descriptions and examples are generated from the versioned JSON Schema files during the documentation build.

insonic immutable artifact manifest

Portable inventory of complete immutable bytes. Hosted model handles without downloadable bytes belong in the speaker-model contract and are not invented digest entries here.

Download artifact-manifest.schema.json

artifacts

Complete artifact entries. Application validation additionally rejects repeated artifact IDs with conflicting content identity.

Value: array.

artifacts[]

One complete immutable artifact with portable byte identity and optional verified durable replicas.

artifacts[].locations

Verified durable locations when available. Availability and leases are runtime state, separate from content identity.

Value: array.

artifacts[].locations[]

Durable managed object location. Keys identify exact objects; credentials and cached materialization paths never appear here.

All of the following constraints apply:

When storage_type is "s3":

Value: object.

Required fields: bucket.

Otherwise:

Disallowed combination: has bucket.

Example

{
  "schema_version": "1.0.3",
  "kind": "artifact-manifest",
  "manifest_id": "44444444-4444-4444-8444-444444444444",
  "workspace_id": "11111111-1111-4111-8111-111111111111",
  "created_at": {
    "iso": "2026-10-04T18:30:00Z",
    "unix_ns": 1791138600000000000
  },
  "artifacts": [
    {
      "artifact_id": "22222222-2222-4222-8222-222222222222",
      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "byte_length": 4096,
      "artifact_kind": "metadata-report",
      "media_type": "application/json",
      "retention_class": "durable",
      "locations": [
        {
          "profile": {
            "profile_id": "33333333-3333-4333-8333-333333333333",
            "profile_revision": 1,
            "adapter_id": "filesystem"
          },
          "storage_type": "filesystem",
          "key": "objects/sha256/01/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
        }
      ]
    }
  ]
}

insonic backend configuration plan

Complete nonsecret initial backend selection. Omitted identities and local defaults are generated by workspace plan. Submit its generated configuration unchanged to reconcile retries.

Download backend-plan.schema.json

profiles

Three independent required backend selections.

profiles.storage

Selected artifact storage profile with an immutable configuration revision.

profiles.storage.configuration

Nonsecret adapter configuration matching adapter_id; conditional rules identify the exact permitted shape.

Exactly one of the following alternatives must match:

profiles.storage.configuration: Alternative 1

Default local filesystem artifact store. The root is a selected location, not a source identity.

Value: Reference: workspace-config.schema.json#/$defs/filesystemConfiguration.

profiles.storage.configuration: Alternative 2

Generic S3 API configuration, applicable to remote providers and user-run filesystem-backed S3 endpoints.

Value: Reference: workspace-config.schema.json#/$defs/s3Configuration.

All of the following constraints apply:

When adapter_id is "filesystem":

When adapter_id is "s3":

profiles.catalog

Selected operational catalog profile with an immutable configuration revision.

profiles.catalog.configuration

Nonsecret adapter configuration matching adapter_id; conditional rules identify the exact permitted shape.

Exactly one of the following alternatives must match:

profiles.catalog.configuration: Alternative 1

Default local SQLite catalog configuration.

Value: Reference: workspace-config.schema.json#/$defs/sqliteConfiguration.

profiles.catalog.configuration: Alternative 2

Full PostgreSQL catalog configuration. Credentials remain outside this document and application transactions retain workspace scope.

Value: Reference: workspace-config.schema.json#/$defs/postgresqlConfiguration.

All of the following constraints apply:

When adapter_id is "sqlite":

When adapter_id is "postgresql":

profiles.graph

Selected graph projection profile with an immutable configuration revision.

profiles.graph.configuration

Nonsecret adapter configuration matching adapter_id; conditional rules identify the exact permitted shape.

Exactly one of the following alternatives must match:

profiles.graph.configuration: Alternative 1

Default embedded LadybugDB projection attached to the owning runtime.

Value: Reference: workspace-config.schema.json#/$defs/ladybugdbConfiguration.

profiles.graph.configuration: Alternative 2

ArcadeDB server graph adapter configuration, distinct from the operational catalog role.

Value: Reference: workspace-config.schema.json#/$defs/arcadedbConfiguration.

profiles.graph.configuration: Alternative 3

Optional user-provided graph adapter configuration. This does not make its engine officially supported or redistributed.

Value: Reference: workspace-config.schema.json#/$defs/communityConfiguration.

All of the following constraints apply:

When adapter_id is "ladybugdb":

When adapter_id is "arcadedb":

When adapter_id is "community":

Example

{
  "schema_version": "1.0.3",
  "kind": "backend-plan",
  "display_name": "Example library",
  "profiles": {
    "storage": {
      "adapter_id": "filesystem",
      "configuration": {
        "root": "artifacts"
      }
    },
    "catalog": {
      "adapter_id": "sqlite",
      "configuration": {
        "path": "catalog.sqlite"
      }
    },
    "graph": {
      "adapter_id": "ladybugdb",
      "configuration": {
        "path": "graph/library.lbug"
      }
    }
  }
}

insonic downloaded base model manifest

Exact downloaded model identity, upstream revision, declared capabilities/license and ordered file digests. Registration does not claim local availability. Acquisition verifies every declared file before an available installation is committed. Credentials remain opaque references and never appear in URLs.

Download base-model-manifest.schema.json

capabilities

Declared adapter capabilities for later selection; registration does not run inference.

Value: array.

capabilities[]

Declared capability name.

Value: string.

files

Ordered required file roles and independently verified byte identities. The application rejects duplicate roles.

Value: array.

files[]

Example

{
  "kind": "base-model-manifest",
  "schema_version": "1.0.3",
  "name": "example-recognizer",
  "model_version": "1.0.0",
  "upstream_revision": "immutable-revision-1",
  "capabilities": [
    "recognition"
  ],
  "license": "Apache-2.0",
  "files": [
    {
      "role": "weights",
      "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "size": 1048576,
      "url": "https://models.example.org/recognizer/1.0.0/weights.bin"
    }
  ]
}

Portable catalog snapshot

Consistent logical catalog export with typed provenance and ordered operational rows. Restoration verifies digest, workspace, supported migration version and all relationships, admits only an empty destination and expires imported authority. It does not copy artifact bytes or activate a different profile.

Download catalog-snapshot.schema.json

records

Typed Records record with scoped associations.

records.artifacts

Deterministically ordered typed records, or null when empty.

Value: array or null.

records.artifacts[]

Typed Artifact record with scoped associations.

records.assets

Deterministically ordered typed records, or null when empty.

Value: array or null.

records.assets[]

Typed Asset record with scoped associations.

records.datasets

Deterministically ordered typed records, or null when empty.

Value: array or null.

records.datasets[]

Typed Dataset record with scoped associations.

records.datasets[].manifest_artifact_id

Derived artifact reference, or null after evidence invalidation.

At least one of the following alternatives must match:

records.datasets[].manifest_artifact_id: Alternative 1

Current managed derived artifact identity.

Value: Reference: common.schema.json#/$defs/uuid.

records.datasets[].manifest_artifact_id: Alternative 2

Value: null.

records.datasets[].invalidated_by

Current invalidation owner, or null for current lineage.

At least one of the following alternatives must match:

records.datasets[].invalidated_by: Alternative 1

Recording or workspace responsible for accepted invalidation.

Value: Reference: common.schema.json#/$defs/uuid.

records.datasets[].invalidated_by: Alternative 2

Value: null.

All of the following constraints apply:

When state is "invalidated":

Otherwise:

records.date_selections

Deterministically ordered typed records, or null when empty.

Value: array or null.

records.date_selections[]

Typed DateSelection record with scoped associations.

records.date_selections[].date_id

Workspace-scoped stable identity; relational provenance is validated by the adapter.

At least one of the following alternatives must match:

records.date_selections[].date_id: Alternative 1

Value: Reference: common.schema.json#/$defs/uuid.

records.date_selections[].date_id: Alternative 2

Value: null.

records.dates

Deterministically ordered typed records, or null when empty.

Value: array or null.

records.dates[]

Typed DateObservation record with scoped associations.

records.dates[].observation_id

Workspace-scoped stable identity; relational provenance is validated by the adapter.

At least one of the following alternatives must match:

records.dates[].observation_id: Alternative 1

Value: Reference: common.schema.json#/$defs/uuid.

records.dates[].observation_id: Alternative 2

Value: null.

records.dates[].offset_seconds

Typed catalog value, or null when unknown.

At least one of the following alternatives must match:

records.dates[].offset_seconds: Alternative 1

Exact signed integer value; adapter enforces the logical field range.

Value: integer.

records.dates[].offset_seconds: Alternative 2

Value: null.

records.dates[].resolved

Typed catalog value, or null when unknown.

At least one of the following alternatives must match:

records.dates[].resolved: Alternative 1

Exact ISO/Unix-nanosecond audit instant; adapter checks agreement.

Value: Reference: common.schema.json#/$defs/utcInstant.

records.dates[].resolved: Alternative 2

Value: null.

records.dates[].rules_version

Typed catalog value, or null when unknown.

At least one of the following alternatives must match:

records.dates[].rules_version: Alternative 1

Typed text value retained without reinterpretation.

Value: string.

records.dates[].rules_version: Alternative 2

Value: null.

records.dates[].zone

Typed catalog value, or null when unknown.

At least one of the following alternatives must match:

records.dates[].zone: Alternative 1

Typed text value retained without reinterpretation.

Value: string.

records.dates[].zone: Alternative 2

Value: null.

records.locations

Deterministically ordered typed records, or null when empty.

Value: array or null.

records.locations[]

Typed ArtifactLocation record with scoped associations.

records.locations[].version

Typed catalog value, or null when unknown.

At least one of the following alternatives must match:

records.locations[].version: Alternative 1

Typed text value retained without reinterpretation.

Value: string.

records.locations[].version: Alternative 2

Value: null.

records.media

Deterministically ordered typed records, or null when empty.

Value: array or null.

records.media[]

Typed Media record with scoped associations.

records.media_assets

Deterministically ordered typed records, or null when empty.

Value: array or null.

records.media_assets[]

Typed MediaAsset record with scoped associations.

records.members

Deterministically ordered typed records, or null when empty.

Value: array or null.

records.members[]

Typed DatasetMember record with scoped associations.

records.metadata

Deterministically ordered typed records, or null when empty.

Value: array or null.

records.metadata[]

Typed MetadataSnapshot record with scoped associations.

records.metadata[].report_artifact_id

Workspace-scoped stable identity; relational provenance is validated by the adapter.

At least one of the following alternatives must match:

records.metadata[].report_artifact_id: Alternative 1

Value: Reference: common.schema.json#/$defs/uuid.

records.metadata[].report_artifact_id: Alternative 2

Value: null.

records.model_artifacts

Deterministically ordered typed records, or null when empty.

Value: array or null.

records.model_artifacts[]

Typed ModelArtifact record with scoped associations.

records.model_associations

Deterministically ordered typed records, or null when empty.

Value: array or null.

records.model_associations[]

Typed ModelAssociation record with scoped associations.

records.models

Deterministically ordered typed records, or null when empty.

Value: array or null.

records.models[]

Typed Model record with scoped associations.

records.observations

Deterministically ordered typed records, or null when empty.

Value: array or null.

records.observations[]

Typed Observation record with scoped associations.

records.observations[].precision

Typed catalog value, or null when unknown.

At least one of the following alternatives must match:

records.observations[].precision: Alternative 1

Typed text value retained without reinterpretation.

Value: string.

records.observations[].precision: Alternative 2

Value: null.

records.observations[].unit

Typed catalog value, or null when unknown.

At least one of the following alternatives must match:

records.observations[].unit: Alternative 1

Typed text value retained without reinterpretation.

Value: string.

records.observations[].unit: Alternative 2

Value: null.

records.profiles

Deterministically ordered typed records, or null when empty.

Value: array or null.

records.profiles[]

Typed Profile record with scoped associations.

records.profiles[].credential_id

Typed catalog value, or null when unknown.

At least one of the following alternatives must match:

records.profiles[].credential_id: Alternative 1

Typed text value retained without reinterpretation.

Value: string.

records.profiles[].credential_id: Alternative 2

Value: null.

records.profiles[].expected_backend_version

Typed catalog value, or null when unknown.

At least one of the following alternatives must match:

records.profiles[].expected_backend_version: Alternative 1

Typed text value retained without reinterpretation.

Value: string.

records.profiles[].expected_backend_version: Alternative 2

Value: null.

records.runs

Deterministically ordered typed records, or null when empty.

Value: array or null.

records.runs[]

Typed TrainingRun record with scoped associations.

records.runs[].preparation_artifact_id

Derived artifact reference, or null after evidence invalidation.

At least one of the following alternatives must match:

records.runs[].preparation_artifact_id: Alternative 1

Current managed derived artifact identity.

Value: Reference: common.schema.json#/$defs/uuid.

records.runs[].preparation_artifact_id: Alternative 2

Value: null.

All of the following constraints apply:

When state is "invalidated":

Otherwise:

records.segments

Deterministically ordered typed records, or null when empty.

Value: array or null.

records.segments[]

Reference to current embedded subtitle/speaker evidence. Timings, attribution payloads and known-person assignments are resolved from the current recording and mapping; they are not copied here.

records.segments[].clip_artifact_id

Optional derived clip identity, or null. A clip does not become assignment authority.

At least one of the following alternatives must match:

records.segments[].clip_artifact_id: Alternative 1

Optional managed prepared clip identity.

Value: Reference: common.schema.json#/$defs/uuid.

records.segments[].clip_artifact_id: Alternative 2

Value: null.

records.speakers

Deterministically ordered typed records, or null when empty.

Value: array or null.

records.speakers[]

Typed Speaker record with scoped associations.

records.versions

Deterministically ordered typed records, or null when empty.

Value: array or null.

records.versions[]

Typed ModelVersion record with scoped associations.

records.versions[].manifest_artifact_id

Derived artifact reference, or null after evidence invalidation.

At least one of the following alternatives must match:

records.versions[].manifest_artifact_id: Alternative 1

Current managed derived artifact identity.

Value: Reference: common.schema.json#/$defs/uuid.

records.versions[].manifest_artifact_id: Alternative 2

Value: null.

All of the following constraints apply:

When state is "invalidated":

Otherwise:

records.library

Current typed records, or null when empty.

Value: array or null.

records.library[]

records.library[].original_publication_id

Current typed catalog value; adapter enforces scoped identity and logical constraints.

At least one of the following alternatives must match:

records.library[].original_publication_id: Alternative 1

Value: Reference: common.schema.json#/$defs/uuid.

records.library[].original_publication_id: Alternative 2

Value: null.

records.library[].subtitle_publication_id

Current typed catalog value; adapter enforces scoped identity and logical constraints.

At least one of the following alternatives must match:

records.library[].subtitle_publication_id: Alternative 1

Value: Reference: common.schema.json#/$defs/uuid.

records.library[].subtitle_publication_id: Alternative 2

Value: null.

records.library[].report_publication_ids

Current raw metadata report publication identities. Replacements remove superseded references and queue physical retirement.

Value: array.

records.library[].report_publication_ids[]

Workspace-scoped managed publication identity.

Value: Reference: common.schema.json#/$defs/uuid.

records.works

Current typed records, or null when empty.

Value: array or null.

records.works[]

records.cleanups

Current typed records, or null when empty.

Value: array or null.

records.cleanups[]

records.cleanups[].legacy_location_id

Optional location-only migration obligation. Pending has no invented admission; completion requires actual retirement.

At least one of the following alternatives must match:

records.cleanups[].legacy_location_id: Alternative 1

Exact legacy location identity requiring selected-store verified adoption.

Value: Reference: common.schema.json#/$defs/uuid.

records.cleanups[].legacy_location_id: Alternative 2

Value: null.

records.base_models

Current typed records, or null when empty.

Value: array or null.

records.base_models[]

records.base_models[].manifest

Exact selected downloaded-model manifest, separate from speaker-trained model lineage. Supported immutable historical documents retain their declared version and original digest.

At least one of the following alternatives must match:

records.base_models[].manifest: Alternative 1

Value: Reference: base-model-manifest.schema.json.

records.base_models[].manifest: Alternative 2

Value: Reference: https://raw.githubusercontent.com/shruggietech/insonic/v1.0.0/schemas/v1.0.0/base-model-manifest.schema.json.

records.base_models[].manifest: Alternative 3

Value: Reference: https://raw.githubusercontent.com/shruggietech/insonic/v1.0.1/schemas/v1.0.1/base-model-manifest.schema.json.

records.base_models[].manifest: Alternative 4

Value: Reference: https://raw.githubusercontent.com/shruggietech/insonic/v1.0.2/schemas/v1.0.2/base-model-manifest.schema.json.

records.base_models[].publication_ids

Ordered verified required model-file publication identities.

Value: array.

records.base_models[].publication_ids[]

Workspace-scoped managed publication identity.

Value: Reference: common.schema.json#/$defs/uuid.

records.recordings

Current authority rows, never alternate derived results.

Value: array or null.

records.recordings[]

Value: Reference: recording.schema.json#/$defs/current.

records.speaker_mappings

Current authority rows, never alternate derived results.

Value: array or null.

records.speaker_mappings[]

Value: Reference: recording.schema.json#/$defs/mapping.

records.speaker_aliases

Current typed records, ordered by stable identity; null or omission denotes an empty domain.

Value: array or null.

records.speaker_aliases[]

Current alias; updates are fenced by the owning speaker aggregate revision.

records.terms

Current typed records, ordered by stable identity; null or omission denotes an empty domain.

Value: array or null.

records.terms[]

Current revisioned recognition term.

records.terms[].variants

Ordered variants, deduplicated only during context compilation.

Value: array.

records.terms[].variants[]

Explicit recognition variant.

Value: string.

records.terms[].speaker_id

Optional known-speaker link.

At least one of the following alternatives must match:

records.terms[].speaker_id: Alternative 1

Optional known-speaker link.

Value: Reference: common.schema.json#/$defs/uuid.

records.terms[].speaker_id: Alternative 2

Value: null.

records.terms[].alias_id

Optional alias link.

At least one of the following alternatives must match:

records.terms[].alias_id: Alternative 1

Optional alias link; must belong to the linked speaker when both are supplied.

Value: Reference: common.schema.json#/$defs/uuid.

records.terms[].alias_id: Alternative 2

Value: null.

records.pipelines

Current typed records, ordered by stable identity; null or omission denotes an empty domain.

Value: array or null.

records.pipelines[]

Current saved pipeline definition; work captures its effective revision separately.

records.extractions

Portable typed extractions, validated against accepted current-state proofs.

Value: array.

records.extractions[]

records.saved_queries

Portable typed saved queries, validated against accepted current-state proofs.

Value: array.

records.saved_queries[]

records.saved_queries[].validations

Immutable backend compatibility findings for this saved version.

Value: array.

records.saved_queries[].validations[]

Compatibility check result.

Value: object.

records.graph_layouts

Portable typed graph layouts, validated against accepted current-state proofs.

Value: array.

records.graph_layouts[]

records.rosters

Current intentional roster headers, independent of transcripts.

Value: array.

records.rosters[]

records.roster_members

Unique references to existing centralized speaker identities.

Value: array.

records.roster_members[]

records.model_aliases

Deterministically ordered alias/source records including revision tombstones.

Value: array or null.

records.model_aliases[]

Typed workspace-scoped portable record.

Value: Reference: common.schema.json#/$defs/modelAlias.

records.model_sources

Deterministically ordered alias/source records including revision tombstones.

Value: array or null.

records.model_sources[]

Typed workspace-scoped portable record.

Value: Reference: common.schema.json#/$defs/modelSource.

records.speaker_outputs

Completed exact outputs preserved when current corpus is invalidated.

Value: array or null.

records.speaker_outputs[]

Immutable speaker output, independent of current preparation validity.

records.speaker_outputs[].metadata

Immutable noncontent output identity, compatibility and origin manifest. Supported immutable historical documents retain their declared version and original digest.

At least one of the following alternatives must match:

records.speaker_outputs[].metadata: Alternative 1

Value: Reference: speaker-model.schema.json.

records.speaker_outputs[].metadata: Alternative 2

Value: Reference: https://raw.githubusercontent.com/shruggietech/insonic/v1.0.0/schemas/v1.0.0/speaker-model.schema.json.

records.speaker_outputs[].metadata: Alternative 3

Value: Reference: https://raw.githubusercontent.com/shruggietech/insonic/v1.0.1/schemas/v1.0.1/speaker-model.schema.json.

records.speaker_outputs[].metadata: Alternative 4

Value: Reference: https://raw.githubusercontent.com/shruggietech/insonic/v1.0.2/schemas/v1.0.2/speaker-model.schema.json.

records.speaker_outputs[].publication_ids

Available durable output publications.

Value: array.

records.speaker_outputs[].publication_ids[]

Exact verified artifact publication.

Value: Reference: common.schema.json#/$defs/uuid.

All of the following constraints apply:

When metadata matches object:

records.speaker_profiles

Explicit exact version selections for roster matching.

Value: array or null.

records.speaker_profiles[]

Revisioned current speaker profile head.

All of the following constraints apply:

When state matches "active":

Otherwise:

records.speaker_checkpoints

Validated resumable state distinct from completed models.

Value: array or null.

records.speaker_checkpoints[]

Immutable producing-attempt checkpoint.

state

Operational tables in dependency order; includes receipts, selections, jobs, attempts, leases, targets and events. Schema 1 has seven tables; schema 2 adds the typed artifact publication/lifecycle journal.

Value: array.

state[]

state[].rows

Ordered complete rows in the table's portable layout; restoration validates width, types and semantic relationships.

Value: array.

state[].rows[]

Operational row cells in the fixed table column order. JSON reports/results are stored as strings; integer cells remain exact.

Value: array.

state[].rows[][]

At least one of the following alternatives must match:

state[].rows[][]: Alternative 1

Value: string.

state[].rows[][]: Alternative 2

Value: integer.

state[].rows[][]: Alternative 3

Value: null.

All of the following constraints apply:

When catalog_schema is 5:

records

Current records contract.

records.speakers

Current speakers contract.

Value: array or null.

records.speakers[]

Current known-speaker identity.

Definition: speaker

Current known-speaker identity.

Definition: speakerAlias

Current alias; updates are fenced by the owning speaker aggregate revision.

Definition: term

Current revisioned recognition term.

Definition: term.variants

Ordered variants, deduplicated only during context compilation.

Value: array.

Definition: term.variants[]

Explicit recognition variant.

Value: string.

Definition: term.speaker_id

Optional known-speaker link.

At least one of the following alternatives must match:

Definition: term.speaker_id: Alternative 1

Optional known-speaker link.

Value: Reference: common.schema.json#/$defs/uuid.

Definition: term.speaker_id: Alternative 2

Value: null.

Definition: term.alias_id

Optional alias link.

At least one of the following alternatives must match:

Definition: term.alias_id: Alternative 1

Optional alias link; must belong to the linked speaker when both are supplied.

Value: Reference: common.schema.json#/$defs/uuid.

Definition: term.alias_id: Alternative 2

Value: null.

Definition: pipeline

Current saved pipeline definition; work captures its effective revision separately.

Example

{
  "kind": "catalog-snapshot",
  "schema_version": "1.0.3",
  "catalog_schema": 1,
  "workspace_id": "10000000-0000-4000-8000-000000000001",
  "revision": 0,
  "records": {
    "profiles": null,
    "artifacts": null,
    "locations": null,
    "media": null,
    "assets": null,
    "media_assets": null,
    "metadata": null,
    "observations": null,
    "dates": null,
    "date_selections": null,
    "speakers": null,
    "segments": null,
    "datasets": null,
    "members": null,
    "runs": null,
    "models": null,
    "versions": null,
    "model_artifacts": null,
    "model_associations": null,
    "library": null,
    "works": null,
    "cleanups": null,
    "base_models": null
  },
  "state": [
    {
      "name": "operation_receipt",
      "rows": []
    },
    {
      "name": "setting_revision",
      "rows": []
    },
    {
      "name": "job",
      "rows": []
    },
    {
      "name": "job_attempt",
      "rows": []
    },
    {
      "name": "workspace_lease",
      "rows": []
    },
    {
      "name": "graph_target",
      "rows": []
    },
    {
      "name": "graph_event",
      "rows": []
    }
  ],
  "digest": "17c5708b98f6e943d890677b193f530dcc759356a9501269ed7a3443f0919d1f"
}

insonic saved graph query

Immutable query definitions with typed parameters and declared backend compatibility. Every execution resolves current sources; presentation state is separate from evidence. Normalized result pages continue rows and relationships independently through one opaque next_cursor; edges may reference endpoints on other pages. Follow until next_cursor is absent, including edge-only pages. Each stream contains at most the requested limit and the result remains byte bounded.

Download graph-query.schema.json

definition

Exactly one normalized application specification or native dialect/text definition.

Exactly one of the following alternatives must match:

definition: normalized

Portable application QuerySpec compiled separately by each official graph adapter.

definition: normalized.filters

Portable application filters. Unknown filters are rejected instead of ignored.

definition: normalized.filters.media_ids

Restrict to explicit media entries.

Value: array.

definition: normalized.filters.media_ids[]

Selected library media entry ID.

Value: Reference: common.schema.json#/$defs/uuid.

definition: normalized.filters.speaker_ids

Current speaker/lineage filter.

Value: array.

definition: normalized.filters.speaker_ids[]

Selected catalog speaker ID.

Value: Reference: common.schema.json#/$defs/uuid.

definition: normalized.filters.recording_dates

Origination calendar filter preserving timezone and undated handling.

definition: normalized.filters.concept_ids

Concept filter for evidence/graph traversal.

Value: array.

definition: normalized.filters.concept_ids[]

Normalized concept ID.

Value: Reference: common.schema.json#/$defs/uuid.

definition: normalized.filters.entity_ids

Stable projected graph node references used as bounded traversal seeds.

Value: array.

definition: normalized.filters.entity_ids[]

Current projected graph node ID.

Value: string.

definition: normalized.traversal

Explicit bounded graph expansion, without an engine-specific query string.

definition: normalized.traversal.relationship_types

Relationship types included in expansion.

Value: array.

definition: normalized.traversal.relationship_types[]

Logical relationship type from the versioned projection schema.

Value: string.

definition: normalized.order_by

Deterministic ordering, with a stable entity-ID tie breaker added by the application if needed.

Value: array.

definition: normalized.order_by[]

One ordered result field.

definition: normalized.pagination

Bounded current-result pagination.

definition: native

Advanced query text with a declared dialect; arbitrary native text is not automatically portable.

definition: native.dialect

Official native dialect or explicitly namespaced unofficial community dialect.

Value: string.

At least one of the following alternatives must match:

definition: native.dialect: Alternative 1

Value: "ladybug-cypher", "arcade-opencypher", "arcade-sql".

definition: native.dialect: Alternative 2

Value: string.

parameters

Named typed parameters, passed as values rather than interpolated query text.

Value: object.

parameters{name}

Typed native-query parameter normalized by the selected adapter.

parameters{name}.value

Parameter value matching its declared logical type; native adapters validate any narrower backend constraints.

At least one of the following alternatives must match:

parameters{name}.value: Alternative 1

Value: string.

parameters{name}.value: Alternative 2

Value: number.

parameters{name}.value: Alternative 3

Value: boolean.

parameters{name}.value: Alternative 4

Value: null.

parameters{name}.value: Alternative 5

Value: array.

parameters{name}.value: Alternative 6

Value: object.

All of the following constraints apply:

When type is "string":

When type is "integer":

value

Exact signed 64-bit integer as a JSON integer or canonical decimal string; the runtime enforces range.

Exactly one of the following alternatives must match:

value: Alternative 1

Value: integer.

value: Alternative 2

Value: string.

When type is "number":

When type is "boolean":

When type is "uuid":

When type is "date-time":

When type is "date":

When type is "array":

When type is "object":

When type is "null":

page

Bounded result pagination with explicit truncation/cursor reporting.

validations

Compatibility checks for selected backend versions. No entry means compatibility has not been established.

Value: array.

validations[]

Recorded compatibility check for one backend/schema/capability target.

validations[].diagnostics

Reasons a saved query is incompatible or limited.

Value: array.

validations[].diagnostics[]

Readable compatibility finding.

Value: string.

All of the following constraints apply:

When status is "validated":

Value: object.

Required fields: backend_version, capability_fingerprint, validated_at.

view

Presentation defaults only. Runtime graph positions are stored separately; saved definitions never retain result snapshots.

view.positions

Saved display positions separate from node data.

Value: array.

view.positions[]

Position of one stable catalog node ID.

Example

{
  "schema_version": "1.0.3",
  "kind": "graph-query",
  "query_id": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
  "revision": 1,
  "workspace_id": "11111111-1111-4111-8111-111111111111",
  "title": "Speaker evidence",
  "access_mode": "read-only",
  "definition": {
    "mode": "normalized",
    "operation": "evidence-traverse",
    "filters": {
      "speaker_ids": [
        "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee"
      ]
    },
    "traversal": {
      "direction": "both",
      "max_depth": 2
    }
  },
  "parameters": {},
  "page": {
    "limit": 100
  },
  "validations": [],
  "view": {
    "layout": "force-directed",
    "positions": []
  }
}

insonic import manifest

Batch import input for the CLI and its GUI wrapper. Syntax validation precedes application validation of source access, calendar values, timezone/DST policy and admission. No approval per item is required for already configured routing.

Download import-manifest.schema.json

items

Inputs in deterministic admission order, with independent partial-result reporting.

Value: array.

items[]

Recording-date defaults and policies. Exact timestamp, calendar date and approximate UTC range are mutually exclusive.

Disallowed combination: the condition matches.

items[].known_speakers

Initial declared identities by UUID or unique exact canonical name/active alias. Empty declares an empty roster.

Value: array.

items[].known_speakers[]

Value: string.

items[].pipeline_id

Configured pipeline UUID. Empty explicitly selects admission only.

Value: string.

At least one of the following alternatives must match:

items[].pipeline_id: Alternative 1

Value: Constant "".

items[].pipeline_id: Alternative 2

Value: Reference: common.schema.json#/$defs/uuid.

Exactly one of the following alternatives must match:

items[]: media

Disallowed combination: has transcript, subtitle.

items[]: Alternative 2

Required fields: source.

Disallowed combination: the condition matches.

items[]: Alternative 3

Required fields: record.

Disallowed combination: kind is "media".

Exactly one of the following alternatives must match:

items[]: Alternative 3: Alternative 1

Required fields: source.

Disallowed combination: the condition matches.

items[]: Alternative 3: Alternative 2

Required fields: transcript.

Disallowed combination: the condition matches.

items[]: Alternative 3: Alternative 3

Required fields: subtitle.

Disallowed combination: the condition matches.

Definition: options

Recording-date defaults and policies. Exact timestamp, calendar date and approximate UTC range are mutually exclusive.

Disallowed combination: the condition matches.

Definition: options.known_speakers

Initial declared identities by UUID or unique exact canonical name/active alias. Empty declares an empty roster.

Value: array.

Definition: options.known_speakers[]

Value: string.

Definition: options.pipeline_id

Configured pipeline UUID. Empty explicitly selects admission only.

Value: string.

At least one of the following alternatives must match:

Definition: options.pipeline_id: Alternative 1

Value: Constant "".

Definition: options.pipeline_id: Alternative 2

Value: Reference: common.schema.json#/$defs/uuid.

Example

{
  "schema_version": "1.0.3",
  "kind": "import-manifest",
  "defaults": {
    "copy": true,
    "timezone": "America/New_York",
    "preset": "Daily recordings"
  },
  "items": [
    {
      "source": "audio/session.wav",
      "originated_at": "2026-10-04T14:30:00"
    },
    {
      "source": "video/session.mp4",
      "originated_on": "2026-10-03",
      "subtitle": "video/session.srt"
    }
  ]
}

Example

{
  "kind": "import-manifest",
  "schema_version": "1.0.3",
  "items": [
    {
      "source": "audio/new.flac",
      "known_speakers": []
    },
    {
      "kind": "media",
      "source": "audio/replacement.flac",
      "record": "44444444-4444-4444-8444-444444444444",
      "replace_audio": true,
      "existing_transcript": "keep",
      "transcript_applies": true,
      "existing_roster": "retain"
    }
  ]
}

insonic durable job event

Versioned ordered event for a durable job/attempt. Event syntax does not establish a committed catalog or graph result: publication receipts/checkpoints and application state transitions retain that authority.

Download job-event.schema.json

progress

Adapter-reported progress; absence is distinct from zero progress.

artifact_refs

Immutable artifact references produced by this event, not temporary paths.

Value: array.

artifact_refs[]

Published logical artifact reference.

Value: Reference: common.schema.json#/$defs/artifactReference.

error

Redacted actionable failure details; unknown commit outcomes remain explicitly reconcilable.

publication

Catalog-to-graph publication state associated with this event.

All of the following constraints apply:

When event_type is "queued":

When event_type matches "attempt-started", "stage-started", "progress", "artifact-published", "checkpoint":

Value: object.

Required fields: attempt_id, attempt_number, claim_generation.

When event_type is "progress":

Value: object.

Required fields: progress.

When event_type is "artifact-published":

When event_type is "checkpoint":

Value: object.

Required fields: checkpoint_id.

When event_type is "completed":

When event_type is "failed":

When event_type is "cancelled":

When event_type is "publication-pending":

publication

Catalog-to-graph publication state associated with this event.

Example

{
  "schema_version": "1.0.3",
  "kind": "job-event",
  "event_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "workspace_id": "11111111-1111-4111-8111-111111111111",
  "job_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
  "sequence": 3,
  "occurred_at": {
    "iso": "2026-10-04T18:32:00Z",
    "unix_ns": 1791138720000000000
  },
  "event_type": "progress",
  "state": "running",
  "attempt_id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc",
  "attempt_number": 1,
  "claim_generation": 1,
  "stage_id": "transcribe",
  "progress": {
    "fraction": 0.5,
    "completed_units": 30,
    "total_units": 60,
    "unit": "seconds"
  }
}

insonic metadata extraction tools

Workspace metadata extractor configuration. Every configured executable has an absolute selected path, exact version and SHA-256. Hash/version qualification happens before extraction, and child processes use hidden noninteractive I/O. Missing or failed extractors record explicit capture outcomes while retaining usable original media.

Download media-tools.schema.json

Definition: tool

One exact local executable selected for metadata extraction.

Definition: tool.support_files

Exact selected support files used by a launcher or interpreter bundle. Each file hash is checked before execution so launcher delegation cannot bypass the pinned package identity.

Value: array.

Definition: tool.support_files[]

Optional exact absolute interpreter executable used to run the selected tool script, independently hash-qualified without ambient PATH or shebang lookup.

Definition: tool.interpreter

Optional exact absolute interpreter executable used to run the selected tool script, independently hash-qualified without ambient PATH or shebang lookup.

Example

{
  "kind": "media-tools",
  "schema_version": "1.0.3",
  "exiftool": {
    "path": "/opt/insonic/tools/exiftool",
    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "version": "13.37"
  },
  "ffprobe": {
    "path": "/opt/insonic/tools/ffprobe",
    "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "version": "8.0"
  }
}

insonic early media metadata snapshot

Immutable capture attempt bound to original media before transformations. It preserves raw extractor reports, qualified normalized observations, MIME interpretations and recording-date precision. Missing metadata differs from unsupported extraction or failure.

Download metadata-snapshot.schema.json

source_artifact

Exact inspected original bytes, with complete digest and length.

Value: Reference: common.schema.json#/$defs/artifactReference.

All of the following constraints apply:

source_artifact: Alternative 1

Value: object.

Required fields: sha256, byte_length.

extractor

Exact capture tool/method and effective nonsecret options.

reports

Immutable complete raw report/payload references when capture produced output.

Value: array.

reports[]

Immutable raw extractor report or retained metadata payload. Application admission verifies complete digest and size.

Value: Reference: common.schema.json#/$defs/artifactReference.

All of the following constraints apply:

reports[]: Alternative 1

Value: object.

Required fields: sha256, byte_length.

observations

Qualified normalized tag facts derived from retained raw reports.

Value: array.

observations[]

A qualified incoming tag instance and normalized interpretation. Raw source content is evidence, never runtime instructions.

observations[].group_path

Ordered qualified group path retaining otherwise colliding tag names.

Value: array.

observations[].group_path[]

One instance-qualified metadata group component.

Value: string.

observations[].raw_value

Original JSON-representable value without replacing it with the normalized interpretation.

At least one of the following alternatives must match:

observations[].raw_value: Alternative 1

Value: string.

observations[].raw_value: Alternative 2

Value: number.

observations[].raw_value: Alternative 3

Value: boolean.

observations[].raw_value: Alternative 4

Value: null.

observations[].raw_value: Alternative 5

Value: object.

observations[].raw_value: Alternative 6

Value: array.

observations[].payload_artifact

Immutable raw extractor report or retained metadata payload. Application admission verifies complete digest and size.

Value: Reference: common.schema.json#/$defs/artifactReference.

All of the following constraints apply:

observations[].payload_artifact: Alternative 1

Value: object.

Required fields: sha256, byte_length.

observations[].normalized

Typed normalized value with method provenance; complete raw values remain separate.

observations[].normalized.value

Normalized value matching value_type; adapter/application validation enforces domain-specific semantics.

At least one of the following alternatives must match:

observations[].normalized.value: Alternative 1

Value: string.

observations[].normalized.value: Alternative 2

Value: number.

observations[].normalized.value: Alternative 3

Value: boolean.

observations[].normalized.value: Alternative 4

Value: null.

observations[].normalized.value: Alternative 5

Value: object.

observations[].normalized.value: Alternative 6

Value: array.

All of the following constraints apply:

When value_type is "text":

When value_type is "integer":

When value_type is "number":

When value_type is "boolean":

When value_type is "instant":

When value_type is "date":

When value_type is "bytes":

When value_type is "object":

When value_type is "list":

When value_type is "unknown":

observations[].warnings

Uncertainty and coverage warnings associated with this observation.

Value: array.

observations[].warnings[]

Readable coverage or interpretation warning without credentials.

Value: string.

At least one of the following alternatives must match:

observations[]: Alternative 1

Value: object.

Required fields: raw_value.

observations[]: Alternative 2

Value: object.

Required fields: payload_artifact.

mime_resolution

Separate source observations and selected preferred MIME interpretation, preserving disagreements.

mime_resolution.observations

Observed file/type facts with their distinct origins.

Value: array.

mime_resolution.observations[]

One type observation.

origination_observations

Recording-date observations at admission. Mutable current selection lives in catalog revisions.

Value: array.

origination_observations[]

Immutable origination observation retaining the received/entered literal and its explicit timezone interpretation.

origination_observations[].timezone

Captured effective IANA zone or offset; the unresolved selector local is not valid in a persisted interpreted capture.

Value: Reference: common.schema.json#/$defs/timezone.

All of the following constraints apply:

origination_observations[].timezone: Alternative 1

Disallowed combination: the condition matches.

origination_observations[].bounds

Optional UTC interpretation bounds for an approximate period. Application checks ordering and preserves the calendar precision.

At least one of the following alternatives must match:

origination_observations[].bounds: Alternative 1

Value: object.

Required fields: earliest.

origination_observations[].bounds: Alternative 2

Value: object.

Required fields: latest.

origination_observations[].assumption_flags

Visible assumptions such as a batch-timezone interpretation.

Value: array.

origination_observations[].assumption_flags[]

Explicit assumption applied during interpretation.

Value: string.

All of the following constraints apply:

When precision is "day":

Value: object.

Required fields: calendar_date.

Disallowed combination: has utc_instant.

When precision is "month":

Value: object.

Required fields: calendar_month.

Disallowed combination: has utc_instant.

When precision is "year":

Value: object.

Required fields: calendar_year.

Disallowed combination: has utc_instant.

When precision is "range":

Value: object.

Required fields: bounds.

Disallowed combination: has utc_instant.

When interpretation_state is "resolved":

When interpretation_state matches "ambiguous", "nonexistent", "invalid", "unknown":

Disallowed combination: has utc_instant.

When precision matches Structured value:

Disallowed combination: has utc_instant.

When interpretation_state is "date-only":

coverage

Capture completeness details without claiming every format has EXIF.

coverage.families

Families actually inspected.

Value: array.

coverage.families[]

Metadata family inspected.

Value: string.

coverage.warnings

Recorded coverage and error warnings.

Value: array.

coverage.warnings[]

Readable extraction limitation or failure description.

Value: string.

All of the following constraints apply:

When capture_state matches "captured", "no-embedded-metadata", "partial":

When capture_state is "no-embedded-metadata":

coverage

Capture completeness details without claiming every format has EXIF.

When capture_state is "captured":

coverage

Capture completeness details without claiming every format has EXIF.

When coverage matches object:

Example

{
  "schema_version": "1.0.3",
  "kind": "metadata-snapshot",
  "snapshot_id": "77777777-7777-4777-8777-777777777777",
  "workspace_id": "11111111-1111-4111-8111-111111111111",
  "source_asset_id": "88888888-8888-4888-8888-888888888888",
  "source_artifact": {
    "artifact_id": "99999999-9999-4999-8999-999999999999",
    "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "byte_length": 1048576
  },
  "captured_at": {
    "iso": "2026-10-04T18:31:00Z",
    "unix_ns": 1791138660000000000
  },
  "capture_state": "captured",
  "extractor": {
    "extractor_id": "metadata-adapter",
    "version": "1",
    "options": {
      "qualified_groups": true
    }
  },
  "reports": [
    {
      "artifact_id": "22222222-2222-4222-8222-222222222222",
      "sha256": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
      "byte_length": 4096
    }
  ],
  "observations": [
    {
      "observation_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
      "family": "container",
      "group_path": [
        "QuickTime",
        "Movie"
      ],
      "tag": "CreateDate",
      "occurrence": 0,
      "raw_value": "2026:10:04 14:30:00",
      "normalized": {
        "value_type": "text",
        "value": "2026:10:04 14:30:00",
        "method": "preserve-literal",
        "method_version": "1"
      }
    }
  ],
  "mime_resolution": {
    "resolver_id": "media-type",
    "resolver_version": "1",
    "preferred_mime_type": "video/mp4",
    "disagreement": false,
    "observations": [
      {
        "basis": "byte-detected",
        "value": "video/mp4"
      }
    ]
  },
  "origination_observations": [
    {
      "observation_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
      "basis": "owner",
      "entered_literal": "2026-10-04",
      "precision": "day",
      "interpretation_state": "date-only",
      "calendar_date": "2026-10-04",
      "timezone": "America/New_York",
      "zone_source": "import-policy",
      "policy_version": "1"
    }
  ],
  "coverage": {
    "families": [
      "container"
    ],
    "truncated": false,
    "warnings": []
  }
}