# Aurora schema versioning — how to discover and pin the current version

The `*.aurora.yaml` schema is versioned via SchemaStore. The catalog at SchemaStore lists every published Aurora schema family with version metadata. The skill needs this when:

- Validating a YAML against the canonical grammar.
- Discovering newly published fields the catalog has added since the project was last bumped.
- Pointing the user at the JSON Schema URL for editor IDE support.

---

## The catalog

The SchemaStore catalog is a single JSON document:

```
https://raw.githubusercontent.com/SchemaStore/schemastore/master/src/api/json/catalog.json
```

Inside, the Aurora entry looks like:

```json
{
  "name": "Aurora Agile Meta-Framework",
  "description": "Yaml for Aurora Agile Meta-Framework",
  "fileMatch": ["*.aurora.yaml", "*.aurora.yml"],
  "url": "https://www.schemastore.org/aurora-1.3.json",
  "versions": {
    "1.0": "https://www.schemastore.org/aurora-1.0.json",
    "1.1": "https://www.schemastore.org/aurora-1.1.json",
    "1.2": "https://www.schemastore.org/aurora-1.2.json",
    "1.3": "https://www.schemastore.org/aurora-1.3.json"
  }
}
```

`url` always points at the **latest** version. `versions` lists every published minor.

---

## How to fetch the current version

Use `WebFetch` (preferred) or `curl` to load the catalog and locate the Aurora entry:

```bash
# Quick lookup of the current version
curl -fsS https://raw.githubusercontent.com/SchemaStore/schemastore/master/src/api/json/catalog.json \
  | jq -r '.schemas[] | select(.name == "Aurora Agile Meta-Framework") | .url'
# → https://www.schemastore.org/aurora-1.3.json
```

From the URL, parse the major.minor (`1.3`) and either:

- Validate the YAML against that exact schema (download the schema, run an Ajv-style validator).
- Reference the schema in the YAML's IDE configuration (most editors auto-discover from `fileMatch`).

---

## When to consult the schema, not just `catalyst-schema`

The [`catalyst-schema`](../../catalyst-schema/SKILL.md) skill encodes Aurora's editorial conventions (naming, descriptions, mandatory fields, DDD semantics). The published JSON schema encodes what is *structurally valid* — the union of every property name and type the codegen accepts.

When designing a new feature or auditing a YAML edit, both must align:

| Need | Source |
|---|---|
| Is field name `tenantId` correct, or should it be `tenant`? | `catalyst-schema` (style and DDD opinions) |
| Is `widget.type: async-multiple-search-select` a valid value? | JSON schema (structural validity) |
| What are the allowed values of `front.detailMode`? | JSON schema (`enum`) |
| Is `front.embedSupport` documented and supported in 1.3? | JSON schema + check published version |
| Should this aggregate have a description? | `catalyst-schema` (says yes) |

If a field is **valid in the JSON schema** but **not yet supported by the codegen**, the gap should land as an OpenSpec proposal against the relevant capability. Likewise, if the codegen supports a field that has not yet made it into the JSON schema, the JSON schema needs a bump.

---

## Pinning the project to a specific version

Most editor integrations pick up `*.aurora.yaml` files via the SchemaStore `fileMatch` automatically. To pin a project to a specific version (e.g. force editors to validate against `1.2` while you migrate to `1.3`), add a YAML directive at the top of each schema file:

```yaml
# yaml-language-server: $schema=https://www.schemastore.org/aurora-1.2.json
version: 0.0.1
boundedContextName: iam
moduleName: account
...
```

The `# yaml-language-server` line is honoured by VS Code's YAML extension and most YAML LSP clients. It overrides the SchemaStore catalog's "latest" pointer for this one file.

---

## What to do when the catalog has bumped but the codegen has not caught up

A version bump in SchemaStore signals that the schema vocabulary has grown. The codegen may or may not have caught up. To check:

1. Note the latest version from the catalog (e.g. `1.3`).
2. Inspect `aurora-catalyst-cli/CHANGELOG.md` and `aurora-catalyst-cli/openspec/specs/` for recent capability additions.
3. If a property exists in `aurora-1.3.json` but no spec or codegen path references it → that property is **forward-declared in the schema** but not yet emitted by the codegen. Edit the YAML to use it freely, but understand the regen will not act on it until the codegen catches up.

This is rare in practice but it does happen during multi-version migrations.
