Carmen LabsCarmen Labs
MView V1

Versioning

How the schema is versioned, how it differs from an individual MView's version, and the URL scheme.

Versioning

There are two independent version numbers involved, and it's easy to conflate them.

Schema version — $schema

The schema itself is versioned via its URL path:

https://schemas.carmenlabs.com/mview/v1/schema.json

v1 is the schema major version. A manifest declares which schema version it conforms to via the $schema field, and that value is a const — a v1 manifest must reference the v1 schema URL exactly. There is no $schema: "v1.2" — schema evolution that doesn't break existing manifests happens within v1 (e.g. new optional fields, new enum values). A breaking change (removing a field, changing required-ness, or changing semantics of an existing field) cannot be published under this schema URL. The V1 contract and tooling remain unchanged.

MView version — version

Each individual mview.json also carries its own semantic version:

"version": "1.0.0"

This tracks the MView itself — its parser and component — not the schema. Bump it when you regenerate or hand-edit the parser or component in a way worth tracking. It has no bearing on which schema the manifest validates against.

Why the URL includes the version

Publishing the schema at the versioned URL /mview/v1/schema.json means:

  • Tooling can pin to a specific schema version and won't be broken by a future breaking change.
  • A manifest is self-describing — $schema tells any validator, editor, or agent exactly which rules apply, without out-of-band coordination.
  • MViews keep validating against the same V1 contract.

Practical implication for implementers

If you're building a runtime or validator, resolve the schema from the manifest's own $schema field. Validate it against the published V1 schema rather than an unversioned or inferred contract.

Versionado

Cómo se versiona el esquema, en qué se diferencia de la versión de una MView individual y el esquema de URL.

Versionado

Hay dos números de versión independientes involucrados, y es fácil confundirlos.

Versión del esquema — $schema

El esquema se versiona mediante la ruta de su URL:

https://schemas.carmenlabs.com/mview/v1/schema.json

v1 es la versión mayor del esquema. Un manifiesto declara a qué versión de esquema se ajusta mediante el campo $schema, y ese valor es un const: un manifiesto v1 debe referenciar exactamente la URL del esquema v1. No existe $schema: "v1.2": la evolución del esquema que no rompe manifiestos existentes ocurre dentro de v1 (por ejemplo, nuevos campos opcionales o nuevos valores de enum). Un cambio incompatible no puede publicarse bajo esta URL. El contrato y el tooling V1 permanecen sin modificaciones.

Versión de MView — version

Cada mview.json individual también lleva su propia versión semántica:

"version": "1.0.0"

Esto rastrea la MView en sí —su parser y componente—, no el esquema. Súbela cuando regeneres o edites a mano el parser o componente de una forma que valga la pena registrar. No afecta contra qué esquema valida el manifiesto.

Por qué la URL incluye la versión

Publicar el esquema en la URL versionada /mview/v1/schema.json significa que:

  • El tooling puede fijarse a una versión específica del esquema y no romperse por un cambio incompatible futuro.
  • Un manifiesto se describe a sí mismo: $schema le dice a cualquier validador, editor o agente exactamente qué reglas aplican, sin coordinación fuera de banda.
  • Las MViews siguen validando contra el mismo contrato V1.

Implicación práctica para implementadores

Si estás construyendo un runtime o validador, resuelve el esquema desde el propio campo $schema del manifiesto. Valídalo contra el esquema V1 publicado, no contra un contrato inferido o sin versión.