JSON contracts

One versioned system schema

insonic uses JSON Schema Draft 2020-12 for configuration, import, artifact/metadata interchange, 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; insonic references its validated artifacts without redefining that format.

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

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

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": "0.0.0",
  "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 saved graph query

Immutable saved query revision with either a portable QuerySpec or declared native dialect, typed parameters and explicit backend validation. Graph layout and pinned results are separate from evidence facts.

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.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: 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":

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

Saved presentation settings that do not change graph facts.

view.positions

Saved display positions separate from node data.

Value: array.

view.positions[]

Position of one stable catalog node ID.

Example

{
  "schema_version": "0.0.0",
  "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

defaults

Batch defaults, overridden by explicit per-item fields. Date and timestamp are mutually exclusive within this object.

Disallowed combination: has originated_at, originated_on.

items

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

Value: array.

items[]

One ordered source input. Per-item fields override batch defaults. Source and subtitle paths resolve relative to the manifest unless explicitly absolute.

Disallowed combination: has originated_at, originated_on.

Example

{
  "schema_version": "0.0.0",
  "kind": "import-manifest",
  "defaults": {
    "copy": true,
    "timezone": "America/New_York",
    "preset": "local"
  },
  "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"
    }
  ]
}

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": "0.0.0",
  "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 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 an immutable interpreted snapshot.

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": "0.0.0",
  "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": []
  }
}

insonic pipeline configuration

Immutable revision of a user-selected capability pipeline. CLI and GUI use this same configuration; local and hosted routes, preparation/training capabilities and credential IDs are explicit.

Download pipeline-config.schema.json

stages

Stage declarations with stable IDs. Application validation constructs a dependency graph and verifies effective options.

Value: array.

stages[]

One capability stage. Dependencies, adapter capability compatibility and binding existence are checked before a job starts.

stages[].execution

Explicit local or hosted routing; failure never selects an unconfigured host.

All of the following constraints apply:

When mode is "local":

Value: object.

Required fields: worker_id.

Disallowed combination: has provider_profile.

Otherwise:

Value: object.

Required fields: provider_profile.

Disallowed combination: has worker_id.

stages[].depends_on

Prerequisite stage IDs. Application validation rejects cycles and unknown IDs.

Value: array.

stages[].depends_on[]

ID of a prerequisite stage in this pipeline.

Value: string.

stages[].inputs

Named adapter inputs resolved from admitted assets and earlier stage outputs.

Value: object.

stages[].inputs{name}

Typed logical binding such as media.original or prepare.audio; never a shell expression.

Value: string.

stages[].retry

Bounded idempotent retry policy, separate from changing provider routing.

Example

{
  "schema_version": "0.0.0",
  "kind": "pipeline-config",
  "pipeline_id": "66666666-6666-4666-8666-666666666666",
  "revision": 1,
  "display_name": "Local transcription",
  "stages": [
    {
      "stage_id": "transcribe",
      "capability": "transcription",
      "adapter_id": "faster-whisper",
      "adapter_contract_version": "1",
      "execution": {
        "mode": "local",
        "worker_id": "faster-whisper-cpu"
      },
      "inputs": {
        "audio": "media.transcription_audio"
      },
      "options": {
        "model": "small",
        "compute_type": "int8"
      },
      "retry": {
        "max_attempts": 2,
        "backoff_seconds": 1
      }
    }
  ]
}

Speaker training dataset snapshot

Portable immutable training corpus selection. Source, speaker, attribution, transcript and preparation revisions are frozen; later training preparation binds final bytes in a separate manifest.

Download speaker-dataset.schema.json

members

Ordered included segment memberships; empty snapshots represent no matching corpus and do not imply runnable training.

Value: array.

members[]

Value: Reference: #/$defs/member.

exclusions

Frozen excluded-segment decisions and their technical or user-supplied reasons.

Value: array.

exclusions[]

Value: Reference: #/$defs/exclusion.

Definition: selection

Exact effective selection recipe, allowing automatic corpus selection without segment-by-segment approval.

Definition: selection.attribution_bases

Allowed assignment bases; an empty array includes every declared basis.

Value: array.

Definition: selection.attribution_bases[]

One included attribution basis.

Value: string.

Definition: selection.source_asset_ids

Optional source filter; an empty array covers the speaker's whole workspace corpus.

Value: array.

Definition: selection.source_asset_ids[]

One included original media asset.

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

Definition: selection.languages

Optional language filter; an empty array is language-independent.

Value: array.

Definition: selection.languages[]

One declared language identifier.

Value: string.

Definition: selection.maximum_duration_us

Upper segment-duration bound, or null when no upper bound is configured.

At least one of the following alternatives must match:

Definition: selection.maximum_duration_us: Alternative 1

Maximum original segment duration considered by this recipe.

Value: integer.

Definition: selection.maximum_duration_us: Alternative 2

Value: null.

Definition: selection.explicitly_excluded_segment_ids

User-selected exclusions applied automatically to this snapshot.

Value: array.

Definition: selection.explicitly_excluded_segment_ids[]

Excluded stable segment identity.

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

Definition: preparation

Frozen requested preparation contract; final prepared bytes are bound by a separate immutable preparation manifest.

Definition: preparation.output_format

Requested audio format, or null when the adapter consumes source streams directly.

At least one of the following alternatives must match:

Definition: preparation.output_format: Alternative 1

Requested prepared audio format.

Value: string.

Definition: preparation.output_format: Alternative 2

Value: null.

Definition: preparation.sample_rate_hz

Requested sample rate, or null when unchanged or not applicable.

At least one of the following alternatives must match:

Definition: preparation.sample_rate_hz: Alternative 1

Requested prepared sample rate in hertz.

Value: integer.

Definition: preparation.sample_rate_hz: Alternative 2

Value: null.

Definition: preparation.channel_count

Requested output channel count, or null when unchanged or not applicable.

At least one of the following alternatives must match:

Definition: preparation.channel_count: Alternative 1

Requested prepared channel count.

Value: integer.

Definition: preparation.channel_count: Alternative 2

Value: null.

Definition: member

One included, ordered, immutable dataset member; all referenced revisions and source bytes are frozen.

Definition: member.diagnostics

Technical findings observed when this member was selected.

Value: array.

Definition: member.diagnostics[]

One method-qualified selection finding.

Value: Reference: speaker-segments.schema.json#/$defs/diagnostic.

Definition: exclusion

One explicit selection exclusion retained for explainable automatic corpus selection.

Definition: exclusion.reason_codes

Declared reasons for exclusion, such as duplicate-source-span or configured-overlap-filter.

Value: array.

Definition: exclusion.reason_codes[]

One machine-readable reason code.

Value: string.

Definition: summary

Totals frozen when selection completes; the application verifies consistency against membership.

Definition: summary.prepared_duration_us

Known prepared duration, or null until preparation is materialized.

At least one of the following alternatives must match:

Definition: summary.prepared_duration_us: Alternative 1

Known prepared duration in integer microseconds.

Value: integer.

Definition: summary.prepared_duration_us: Alternative 2

Value: null.

Definition: summary.diagnostic_counts

Counts keyed by declared technical diagnostic code.

Value: object.

Definition: summary.diagnostic_counts{name}

Value: integer.

Definition: summary.languages

Language identifiers observed or selected for the included corpus.

Value: array.

Definition: summary.languages[]

One language identifier.

Value: string.

Example

{
  "schema_version": "0.0.0",
  "kind": "speaker-dataset",
  "workspace_id": "00000000-0000-4000-8000-00000000000a",
  "dataset_snapshot_id": "00000000-0000-4000-8000-00000000000b",
  "speaker_id": "00000000-0000-4000-8000-000000000006",
  "speaker_identity_revision": 1,
  "catalog_revision": 1,
  "created_at": {
    "iso": "2026-10-04T20:01:00Z",
    "unix_ns": 1791144060000000000
  },
  "manifest_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "selection": {
    "recipe_id": "00000000-0000-4000-8000-00000000000c",
    "recipe_revision": 1,
    "preset": "speech-clean",
    "preset_version": "1.0.0",
    "attribution_bases": [],
    "source_asset_ids": [],
    "languages": [],
    "minimum_duration_us": 0,
    "maximum_duration_us": null,
    "explicitly_excluded_segment_ids": [],
    "options": {
      "exclude_duplicate_source_spans": true
    }
  },
  "preparation": {
    "adapter_id": "example.audio-preparation",
    "contract_version": "1",
    "adapter_version": "1.0.0",
    "options": {
      "normalize": false
    },
    "transcript_required": false,
    "output_format": "wav-pcm-s16le",
    "sample_rate_hz": 16000,
    "channel_count": 1
  },
  "members": [
    {
      "ordinal": 0,
      "segment_id": "00000000-0000-4000-8000-000000000007",
      "segment_revision": 1,
      "source": {
        "media_entry_id": "00000000-0000-4000-8000-000000000001",
        "source_asset_id": "00000000-0000-4000-8000-000000000002",
        "source_artifact": {
          "artifact_id": "00000000-0000-4000-8000-000000000003",
          "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "byte_length": 640000
        },
        "stream_id": "00000000-0000-4000-8000-000000000004",
        "stream_index": 0,
        "channels": [
          0
        ],
        "channel_policy": "preserve",
        "interval": {
          "start_us": 1000000,
          "end_us": 3000000
        }
      },
      "processing_run_id": "00000000-0000-4000-8000-000000000008",
      "voice_id": "00000000-0000-4000-8000-000000000009",
      "attribution": {
        "attribution_id": "00000000-0000-4000-8000-000000000005",
        "revision": 1,
        "speaker_id": "00000000-0000-4000-8000-000000000006",
        "speaker_identity_revision": 1,
        "basis": "acoustic-comparison",
        "method": "example.voice-matcher",
        "confidence": {
          "value": 0.88,
          "scale": "unit-interval",
          "method_version": "1.0.0"
        }
      },
      "diagnostics": []
    }
  ],
  "exclusions": [],
  "summary": {
    "segment_count": 1,
    "source_asset_count": 1,
    "original_duration_us": 2000000,
    "prepared_duration_us": null,
    "excluded_segment_count": 0,
    "diagnostic_counts": {},
    "languages": []
  }
}

Speaker model version manifest

Portable exact-version model descriptor preserving the originating speaker, frozen training corpus, preparation, artifacts/checkpoints, provider identity, declared compatibility and license metadata. Current family associations and availability remain revisioned catalog state.

Download speaker-model.schema.json

checkpoints

Optional immutable checkpoints retained with the producing training run.

Value: array.

checkpoints[]

One training checkpoint and resume declaration.

Value: Reference: #/$defs/checkpoint.

license_declarations

Declared upstream/output licenses and explicit unknown declarations.

Value: array.

license_declarations[]

One source-qualified license/attribution statement.

Value: Reference: #/$defs/licenseDeclaration.

evaluations

Optional method-qualified metrics produced before publication.

Value: array.

evaluations[]

One measured evaluation report.

Value: Reference: #/$defs/evaluation.

diagnostics

Technical findings recorded at publication; later lineage/availability findings are separate revisioned catalog observations.

Value: array.

diagnostics[]

One method-qualified model diagnostic.

Value: Reference: speaker-segments.schema.json#/$defs/diagnostic.

Definition: baseModel

Exact upstream/base-model identity when training depends on an existing model; no installed path or secret-bearing URL is retained.

Definition: baseModel.revision

Upstream revision, or null when the provider supplies none.

At least one of the following alternatives must match:

Definition: baseModel.revision: Alternative 1

Declared immutable upstream revision.

Value: string.

Definition: baseModel.revision: Alternative 2

Value: null.

Definition: baseModel.sha256

Known immutable content digest, or null for a provider-managed model without downloadable bytes.

At least one of the following alternatives must match:

Definition: baseModel.sha256: Alternative 1

Verified base-model content digest.

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

Definition: baseModel.sha256: Alternative 2

Value: null.

Definition: baseModel.format

Known model format, or null when the provider does not declare it.

At least one of the following alternatives must match:

Definition: baseModel.format: Alternative 1

Declared base-model serialization format.

Value: string.

Definition: baseModel.format: Alternative 2

Value: null.

Definition: provider

Execution identity sufficient to distinguish local and hosted training provenance.

Definition: datasetReference

Immutable dataset lineage used by this exact model version.

Definition: datasetReference.attribution_revisions

Exact attribution observation revisions represented by selected members.

Value: array.

Definition: datasetReference.attribution_revisions[]

One frozen attribution identity/revision pair.

Definition: preparationReference

Immutable receipt binding every final training input back to the frozen dataset members.

Definition: preparationReference.artifact

Published preparation manifest bytes, including exact member/input-artifact maps.

All of the following constraints apply:

Definition: preparationReference.artifact: Alternative 1

Published preparation manifest bytes, including exact member/input-artifact maps.

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

Definition: preparationReference.artifact: Alternative 2

Value: object.

Required fields: sha256, byte_length.

Definition: preparationReference.input_artifact_ids

Ordered final audio/text input artifact IDs consumed by this run.

Value: array.

Definition: preparationReference.input_artifact_ids[]

One final immutable training input artifact.

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

Definition: training

Durable training execution and all immutable input identities for this published model version.

Definition: training.base_model

Base-model dependency, or null when training did not use one.

At least one of the following alternatives must match:

Definition: training.base_model: Alternative 1

Exact upstream/base-model identity.

Value: Reference: #/$defs/baseModel.

Definition: training.base_model: Alternative 2

Value: null.

Definition: modelArtifact

One immutable output file belonging to this model version.

Definition: modelArtifact.artifact

Verified durable output artifact identity and complete byte digest/length.

All of the following constraints apply:

Definition: modelArtifact.artifact: Alternative 1

Verified durable output artifact identity and complete byte digest/length.

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

Definition: modelArtifact.artifact: Alternative 2

Value: object.

Required fields: sha256, byte_length.

Definition: modelArtifact.required_for

Operations that require this artifact, using declared operation identifiers.

Value: array.

Definition: modelArtifact.required_for[]

One supported operation identifier.

Value: string.

Definition: modelArtifact.dependencies

Other immutable artifact IDs required to interpret this output.

Value: array.

Definition: modelArtifact.dependencies[]

Required companion artifact identity.

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

Definition: hostedModel

Provider-managed model output; the handle is a stable nonsecret identifier rather than downloadable weights.

Definition: hostedModel.supported_operations

Operations supported by this hosted model according to its adapter declaration.

Value: array.

Definition: hostedModel.supported_operations[]

One supported operation.

Value: string.

Definition: hostedModel.retrieval_adapter_id

Declared download adapter, or null when weights are not retrievable.

At least one of the following alternatives must match:

Definition: hostedModel.retrieval_adapter_id: Alternative 1

Adapter capable of retrieving weights.

Value: string.

Definition: hostedModel.retrieval_adapter_id: Alternative 2

Value: null.

Definition: outputs

Validated output manifest; at least one durable artifact or hosted model handle must exist.

Definition: outputs.artifacts

Durable files available for exact-version retrieval.

Value: array.

Definition: outputs.artifacts[]

One verified output file.

Value: Reference: #/$defs/modelArtifact.

At least one of the following alternatives must match:

Definition: outputs: Alternative 1

Definition: outputs: Alternative 2

Value: object.

Required fields: hosted_model.

Definition: compatibility

Declared compatibility of this version; declarations are recorded without claiming unperformed runtime verification.

Definition: compatibility.architecture

Model architecture, or null when undeclared by the producing provider.

At least one of the following alternatives must match:

Definition: compatibility.architecture: Alternative 1

Declared model architecture.

Value: string.

Definition: compatibility.architecture: Alternative 2

Value: null.

Definition: compatibility.supported_operations

Operations this model version declares it can support.

Value: array.

Definition: compatibility.supported_operations[]

One operation identifier.

Value: string.

Definition: compatibility.consumers

Consumer adapter requirements for local or hosted use.

Value: array.

Definition: compatibility.consumers[]

Compatibility declaration for one consuming adapter.

Definition: compatibility.consumers[].accepted_formats

Formats accepted by this consuming adapter.

Value: array.

Definition: compatibility.consumers[].accepted_formats[]

One model format.

Value: string.

Definition: compatibility.runtime_dependencies

Declared software/runtime dependencies; no local install paths are carried.

Value: array.

Definition: compatibility.runtime_dependencies[]

One dependency compatibility declaration.

Definition: compatibility.sample_rate_hz

Declared input/output sample rate where relevant, or null when not applicable or undeclared.

At least one of the following alternatives must match:

Definition: compatibility.sample_rate_hz: Alternative 1

Value: integer.

Definition: compatibility.sample_rate_hz: Alternative 2

Value: null.

Definition: compatibility.channel_count

Declared audio channel count where relevant, or null when not applicable or undeclared.

At least one of the following alternatives must match:

Definition: compatibility.channel_count: Alternative 1

Value: integer.

Definition: compatibility.channel_count: Alternative 2

Value: null.

Definition: compatibility.languages

Declared supported language identifiers; an empty array makes no language-support claim.

Value: array.

Definition: compatibility.languages[]

One declared language identifier.

Value: string.

Definition: checkpoint

Immutable training checkpoint and its resume-compatibility declaration; a checkpoint does not itself assert a completed model.

Definition: checkpoint.artifact

Optional verified checkpoint bytes.

All of the following constraints apply:

Definition: checkpoint.artifact: Alternative 1

Optional verified checkpoint bytes.

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

Definition: checkpoint.artifact: Alternative 2

Value: object.

Required fields: sha256, byte_length.

Definition: checkpoint.base_model

Required base-model identity for resume, or null when none is required.

At least one of the following alternatives must match:

Definition: checkpoint.base_model: Alternative 1

Exact base-model requirement for resume.

Value: Reference: #/$defs/baseModel.

Definition: checkpoint.base_model: Alternative 2

Value: null.

At least one of the following alternatives must match:

Definition: checkpoint: Alternative 1

Value: object.

Required fields: artifact.

Definition: checkpoint: Alternative 2

Value: object.

Required fields: hosted_handle.

Definition: licenseDeclaration

License/attribution statement preserved as metadata, with explicit unknown values rather than an invented eligibility policy.

Definition: licenseDeclaration.declared_license

Declared license, or null when no declaration was supplied.

At least one of the following alternatives must match:

Definition: licenseDeclaration.declared_license: Alternative 1

Declared license expression or upstream name.

Value: string.

Definition: licenseDeclaration.declared_license: Alternative 2

Value: null.

Definition: licenseDeclaration.attribution

Supplied attribution text, or null when absent.

At least one of the following alternatives must match:

Definition: licenseDeclaration.attribution: Alternative 1

Required or supplied attribution text.

Value: string.

Definition: licenseDeclaration.attribution: Alternative 2

Value: null.

Definition: evaluation

Method-qualified training/evaluation metrics; no unmeasured quality claim is implied.

Definition: evaluation.metrics

Named measurements reported by this method; absent measurements are not fabricated.

Value: object.

Definition: evaluation.metrics{name}

At least one of the following alternatives must match:

Definition: evaluation.metrics{name}: Alternative 1

Value: number.

Definition: evaluation.metrics{name}: Alternative 2

Value: string.

Definition: evaluation.metrics{name}: Alternative 3

Value: null.

Example

{
  "schema_version": "0.0.0",
  "kind": "speaker-model",
  "workspace_id": "00000000-0000-4000-8000-00000000000a",
  "model_family_id": "00000000-0000-4000-8000-000000000014",
  "model_version_id": "00000000-0000-4000-8000-000000000015",
  "originating_speaker_id": "00000000-0000-4000-8000-000000000006",
  "originating_speaker_identity_revision": 1,
  "created_at": {
    "iso": "2026-10-04T20:05:00Z",
    "unix_ns": 1791144300000000000
  },
  "manifest_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "display_name": "Example speaker model",
  "training": {
    "training_run_id": "00000000-0000-4000-8000-00000000000d",
    "job_id": "00000000-0000-4000-8000-00000000000e",
    "producing_attempt_id": "00000000-0000-4000-8000-00000000000f",
    "pipeline_id": "00000000-0000-4000-8000-000000000010",
    "pipeline_revision": 1,
    "dataset": {
      "dataset_snapshot_id": "00000000-0000-4000-8000-00000000000b",
      "manifest_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "originating_speaker_id": "00000000-0000-4000-8000-000000000006",
      "speaker_identity_revision": 1,
      "attribution_revisions": [
        {
          "attribution_id": "00000000-0000-4000-8000-000000000005",
          "revision": 1
        }
      ]
    },
    "preparation": {
      "preparation_manifest_id": "00000000-0000-4000-8000-000000000011",
      "manifest_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "artifact": {
        "artifact_id": "00000000-0000-4000-8000-000000000012",
        "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "byte_length": 1024
      },
      "input_artifact_ids": [
        "00000000-0000-4000-8000-000000000013"
      ],
      "adapter_id": "example.audio-preparation",
      "adapter_version": "1.0.0",
      "options": {
        "normalize": false
      }
    },
    "provider": {
      "execution": "local",
      "provider_id": "local",
      "adapter_id": "example.voice-training",
      "contract_version": "1",
      "adapter_version": "1.0.0"
    },
    "base_model": null,
    "parameters": {
      "epochs": 2
    },
    "started_at": {
      "iso": "2026-10-04T20:02:00Z",
      "unix_ns": 1791144120000000000
    },
    "completed_at": {
      "iso": "2026-10-04T20:04:00Z",
      "unix_ns": 1791144240000000000
    }
  },
  "outputs": {
    "artifacts": [
      {
        "role": "weights",
        "artifact": {
          "artifact_id": "00000000-0000-4000-8000-000000000016",
          "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "byte_length": 4096
        },
        "format": "example-voice-format",
        "required_for": [
          "voice-comparison"
        ],
        "dependencies": []
      }
    ]
  },
  "compatibility": {
    "model_kind": "voice-embedding",
    "architecture": "example-encoder",
    "supported_operations": [
      "voice-comparison"
    ],
    "consumers": [
      {
        "adapter_id": "example.voice-matcher",
        "contract_version": "1",
        "implementation_version_range": "1.x",
        "accepted_formats": [
          "example-voice-format"
        ]
      }
    ],
    "runtime_dependencies": [],
    "sample_rate_hz": 16000,
    "channel_count": 1,
    "languages": []
  },
  "checkpoints": [],
  "license_declarations": [
    {
      "scope": "output",
      "declared_license": null,
      "attribution": null,
      "source_basis": "provider-report"
    }
  ],
  "evaluations": [],
  "diagnostics": []
}

Example

{
  "schema_version": "0.0.0",
  "kind": "speaker-model",
  "workspace_id": "00000000-0000-4000-8000-00000000000a",
  "model_family_id": "00000000-0000-4000-8000-000000000014",
  "model_version_id": "00000000-0000-4000-8000-000000000017",
  "originating_speaker_id": "00000000-0000-4000-8000-000000000006",
  "originating_speaker_identity_revision": 1,
  "created_at": {
    "iso": "2026-10-04T20:05:00Z",
    "unix_ns": 1791144300000000000
  },
  "manifest_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "display_name": "Example speaker model",
  "training": {
    "training_run_id": "00000000-0000-4000-8000-00000000000d",
    "job_id": "00000000-0000-4000-8000-00000000000e",
    "producing_attempt_id": "00000000-0000-4000-8000-00000000000f",
    "pipeline_id": "00000000-0000-4000-8000-000000000010",
    "pipeline_revision": 1,
    "dataset": {
      "dataset_snapshot_id": "00000000-0000-4000-8000-00000000000b",
      "manifest_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "originating_speaker_id": "00000000-0000-4000-8000-000000000006",
      "speaker_identity_revision": 1,
      "attribution_revisions": [
        {
          "attribution_id": "00000000-0000-4000-8000-000000000005",
          "revision": 1
        }
      ]
    },
    "preparation": {
      "preparation_manifest_id": "00000000-0000-4000-8000-000000000011",
      "manifest_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "artifact": {
        "artifact_id": "00000000-0000-4000-8000-000000000012",
        "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "byte_length": 1024
      },
      "input_artifact_ids": [
        "00000000-0000-4000-8000-000000000013"
      ],
      "adapter_id": "example.audio-preparation",
      "adapter_version": "1.0.0",
      "options": {
        "normalize": false
      }
    },
    "provider": {
      "execution": "hosted",
      "provider_id": "example.hosted-training",
      "adapter_id": "example.hosted-voice-training",
      "contract_version": "1",
      "adapter_version": "1.0.0",
      "endpoint": "https://training.example.com",
      "credential_id": "00000000-0000-4000-8000-000000000018"
    },
    "base_model": null,
    "parameters": {
      "epochs": 2
    },
    "started_at": {
      "iso": "2026-10-04T20:02:00Z",
      "unix_ns": 1791144120000000000
    },
    "completed_at": {
      "iso": "2026-10-04T20:04:00Z",
      "unix_ns": 1791144240000000000
    }
  },
  "outputs": {
    "artifacts": [],
    "hosted_model": {
      "provider_id": "example.hosted-training",
      "provider_model_id": "model-example-001",
      "downloadable": false,
      "supported_operations": [
        "voice-comparison"
      ],
      "retrieval_adapter_id": null
    }
  },
  "compatibility": {
    "model_kind": "voice-embedding",
    "architecture": null,
    "supported_operations": [
      "voice-comparison"
    ],
    "consumers": [
      {
        "adapter_id": "example.hosted-voice-matcher",
        "contract_version": "1",
        "implementation_version_range": "1.x",
        "accepted_formats": [
          "provider-handle"
        ]
      }
    ],
    "runtime_dependencies": [],
    "sample_rate_hz": null,
    "channel_count": null,
    "languages": []
  },
  "checkpoints": [],
  "license_declarations": [
    {
      "scope": "output",
      "declared_license": null,
      "attribution": null,
      "source_basis": "provider-report"
    }
  ],
  "evaluations": [],
  "diagnostics": []
}

Speaker audio segment catalog

Portable speaker segment query/export result. Source intervals and attribution revisions remain tied to immutable admitted media, across the whole workspace library.

Download speaker-segments.schema.json

speaker_filter

Requested speaker identity, or null for an unfiltered segment result.

At least one of the following alternatives must match:

speaker_filter: Alternative 1

Catalog speaker requested by this query.

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

speaker_filter: Alternative 2

Value: null.

segments

Ordered source-linked segment records; an empty query result is valid.

Value: array.

segments[]

Value: Reference: #/$defs/segment.

next_cursor

Pagination continuation token, or null when complete.

At least one of the following alternatives must match:

next_cursor: Alternative 1

Opaque continuation cursor without secrets.

Value: string.

next_cursor: Alternative 2

Value: null.

Definition: source

Immutable original audio/video source and selected audio channels; no storage path or transient URL is carried here.

Definition: source.source_artifact

Byte identity of the admitted original media artifact.

All of the following constraints apply:

Definition: source.source_artifact: Alternative 1

Byte identity of the admitted original media artifact.

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

Definition: source.source_artifact: Alternative 2

Value: object.

Required fields: sha256, byte_length.

Definition: source.channels

Zero-based original channel indices used for this segment.

Value: array.

Definition: source.channels[]

Value: integer.

Definition: attribution

Frozen attribution observation distinguishing a catalog speaker from a run-local acoustic voice.

Definition: attribution.speaker_id

Assigned catalog speaker UUID, or null for an unresolved voice.

At least one of the following alternatives must match:

Definition: attribution.speaker_id: Alternative 1

Catalog speaker assigned by this observation.

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

Definition: attribution.speaker_id: Alternative 2

Value: null.

Definition: attribution.speaker_identity_revision

Speaker identity revision, or null when the speaker is unresolved.

At least one of the following alternatives must match:

Definition: attribution.speaker_identity_revision: Alternative 1

Exact speaker identity revision supporting this assignment.

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

Definition: attribution.speaker_identity_revision: Alternative 2

Value: null.

Definition: attribution.confidence

Optional method-qualified confidence diagnostic, or null when absent.

At least one of the following alternatives must match:

Definition: attribution.confidence: Alternative 1

Method-qualified confidence diagnostic.

Definition: attribution.confidence: Alternative 2

Value: null.

All of the following constraints apply:

When speaker_id matches null:

Otherwise:

Definition: diagnostic

A nonsecret method-qualified processing or selection finding.

Definition: transcript

Exact selected transcript/cue evidence required by a segment or training member.

Definition: transcript.cue_ids

Cueson cue identifiers scoped to the transcript revision.

Value: array.

Definition: transcript.cue_ids[]

One source cue ID.

Value: string.

Definition: preparedAudio

Materialized audio and its reproducible mapping back to the original source.

Definition: preparedAudio.audio_artifact

Immutable extracted/prepared audio bytes.

All of the following constraints apply:

Definition: preparedAudio.audio_artifact: Alternative 1

Immutable extracted/prepared audio bytes.

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

Definition: preparedAudio.audio_artifact: Alternative 2

Value: object.

Required fields: sha256, byte_length.

Definition: preparedAudio.time_map_artifact

Immutable mapping from prepared audio intervals to original-source intervals.

All of the following constraints apply:

Definition: preparedAudio.time_map_artifact: Alternative 1

Immutable mapping from prepared audio intervals to original-source intervals.

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

Definition: preparedAudio.time_map_artifact: Alternative 2

Value: object.

Required fields: sha256, byte_length.

Definition: preparedAudio.transform_artifact

Immutable receipt naming exact transforms, effective options and tool versions.

All of the following constraints apply:

Definition: preparedAudio.transform_artifact: Alternative 1

Immutable receipt naming exact transforms, effective options and tool versions.

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

Definition: preparedAudio.transform_artifact: Alternative 2

Value: object.

Required fields: sha256, byte_length.

Definition: segment

One immutable boundary revision of a speaker audio segment, including its selected attribution at the exported catalog revision.

Definition: segment.diagnostics

Technical quality and overlap findings; no mandatory human approval is implied.

Value: array.

Definition: segment.diagnostics[]

Value: Reference: #/$defs/diagnostic.

Example

{
  "schema_version": "0.0.0",
  "kind": "speaker-segments",
  "workspace_id": "00000000-0000-4000-8000-00000000000a",
  "catalog_revision": 1,
  "generated_at": {
    "iso": "2026-10-04T20:00:00Z",
    "unix_ns": 1791144000000000000
  },
  "speaker_filter": "00000000-0000-4000-8000-000000000006",
  "segments": [
    {
      "segment_id": "00000000-0000-4000-8000-000000000007",
      "segment_revision": 1,
      "source": {
        "media_entry_id": "00000000-0000-4000-8000-000000000001",
        "source_asset_id": "00000000-0000-4000-8000-000000000002",
        "source_artifact": {
          "artifact_id": "00000000-0000-4000-8000-000000000003",
          "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "byte_length": 640000
        },
        "stream_id": "00000000-0000-4000-8000-000000000004",
        "stream_index": 0,
        "channels": [
          0
        ],
        "channel_policy": "preserve",
        "interval": {
          "start_us": 1000000,
          "end_us": 3000000
        }
      },
      "processing_run_id": "00000000-0000-4000-8000-000000000008",
      "voice_id": "00000000-0000-4000-8000-000000000009",
      "attribution": {
        "attribution_id": "00000000-0000-4000-8000-000000000005",
        "revision": 1,
        "speaker_id": "00000000-0000-4000-8000-000000000006",
        "speaker_identity_revision": 1,
        "basis": "acoustic-comparison",
        "method": "example.voice-matcher",
        "confidence": {
          "value": 0.88,
          "scale": "unit-interval",
          "method_version": "1.0.0"
        }
      },
      "diagnostics": []
    }
  ],
  "next_cursor": null
}

insonic workspace configuration

Versioned nonsecret configuration selecting artifact, catalog and graph adapters independently. Filesystem/SQLite/LadybugDB are defaults, while S3/PostgreSQL/ArcadeDB have full planned application support.

Download workspace-config.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: #/$defs/filesystemConfiguration.

profiles.storage.configuration: Alternative 2

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

Value: Reference: #/$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: #/$defs/sqliteConfiguration.

profiles.catalog.configuration: Alternative 2

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

Value: Reference: #/$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: #/$defs/ladybugdbConfiguration.

profiles.graph.configuration: Alternative 2

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

Value: Reference: #/$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: #/$defs/communityConfiguration.

All of the following constraints apply:

When adapter_id is "ladybugdb":

When adapter_id is "arcadedb":

When adapter_id is "community":

filesystem configuration

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

s3 configuration

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

All of the following constraints apply:

When authentication is "credential":

Value: object.

Required fields: credential_id.

sqlite configuration

Default local SQLite catalog configuration.

postgresql configuration

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

ladybugdb configuration

Default embedded LadybugDB projection attached to the owning runtime.

arcadedb configuration

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

community configuration

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

Example

{
  "schema_version": "0.0.0",
  "kind": "workspace-config",
  "workspace_id": "11111111-1111-4111-8111-111111111111",
  "display_name": "My library",
  "control_directory": "/home/user/MediaLibrary",
  "default_import_timezone": "local",
  "profiles": {
    "storage": {
      "profile_id": "33333333-3333-4333-8333-333333333333",
      "profile_revision": 1,
      "adapter_id": "filesystem",
      "contract_version": "1",
      "configuration": {
        "root": "objects"
      }
    },
    "catalog": {
      "profile_id": "44444444-4444-4444-8444-444444444444",
      "profile_revision": 1,
      "adapter_id": "sqlite",
      "contract_version": "1",
      "configuration": {
        "path": "catalog.sqlite"
      }
    },
    "graph": {
      "profile_id": "55555555-5555-4555-8555-555555555555",
      "profile_revision": 1,
      "adapter_id": "ladybugdb",
      "contract_version": "1",
      "configuration": {
        "path": "graph/library.lbug"
      }
    }
  }
}