diff --git a/schemas/README.md b/schemas/README.md index 744a2fb..e4cd2a8 100644 --- a/schemas/README.md +++ b/schemas/README.md @@ -60,16 +60,29 @@ must contain. [IN-003](https://github.com/AMWA-TV/in-003) is an AMWA draft, at `v1alpha1`, for a media function resource manifest. The repository publishes no tags or releases yet, so dmfdeploy tracks it at a pinned commit, currently -[`acfa2b9`](https://github.com/AMWA-TV/in-003/tree/acfa2b9f7cb71874df2df264c746a6b72b208cab). - -The descriptor stays dmfdeploy's own format. It aligns with IN-003 by field -name and through a generated export. This repository links to IN-003 and uses -its field names, and it copies none of its schema or prose. +[`fd5f036`](https://github.com/AMWA-TV/in-003/tree/fd5f0363b0e6a634e9d98e2c64e2d89157d74cef). +The move from the earlier pin leaves the manifest schema and +`docs/Overview.md` unchanged. Upstream reorganised its examples and added a +`lib/mxl` submodule (with `.gitmodules`), a high-level JT-DMF PDF and edits to +its root `README.md`. + +The descriptor stays dmfdeploy's own format. The plan is to align it with +IN-003 by field name and shape, and to offer a generated export. This +repository links to IN-003 and uses its field names, and it copies none of its +schema or prose. + +The decision is that IN-003 field names are authoritative. The descriptor is +to be a superset: where a descriptor field means the same thing as an IN-003 +field, it takes the IN-003 name and shape, and fields that only the descriptor +needs are additions. The descriptor doesn't meet this yet. Some names already +match, and some shapes differ, as the table shows. The alignment is still to +be implemented under +[dmfdeploy/dmfdeploy#746](https://github.com/dmfdeploy/dmfdeploy/issues/746). ### Shared field names -Where a descriptor field means the same thing as an IN-003 field, it uses the -IN-003 name. The IN-003 paths below are manifest paths. A port maps to an +The descriptor fields below already use the IN-003 name for the same meaning. +The Note column says where the shape still differs today. The IN-003 paths below are manifest paths. A port maps to an entry in `spec.inputs` when its `direction` is `in`, and to an entry in `spec.outputs` when it's `out`; the table writes either list as `spec.`. @@ -77,11 +90,11 @@ entry in `spec.inputs` when its `direction` is `in`, and to an entry in |---|---|---| | `ports[].geometry.frame_width` | `spec.[].format.video.frame_width` | Width in pixels. | | `ports[].geometry.frame_height` | `spec.[].format.video.frame_height` | Height in pixels. | -| `ports[].geometry.frame_rate` | `spec.[].format.video.frame_rate` | The descriptor holds a numerator and a denominator; IN-003 holds a string. The export converts it. | +| `ports[].geometry.frame_rate` | `spec.[].format.video.frame_rate` | Differs in shape today: the descriptor holds a numerator and a denominator, and IN-003 holds a string. To align under #746. | | `ports[].geometry.sample_rate` | `spec.[].format.audio.sample_rate` | Sample rate in hertz. | | `ports[].geometry.channels` | `spec.[].format.audio.channels` | Number of audio channels. | -| `placement.host_capabilities.cpu` | `spec.requirements.host_capabilities.cpu.features` | The descriptor lists feature names as placement hints; IN-003 puts them under requirements. | -| `placement.host_capabilities.network` | `spec.requirements.host_capabilities.network[].features` | Feature names only. IN-003 also describes each network interface. | +| `placement.host_capabilities.cpu` | `spec.requirements.host_capabilities.cpu.features` | Differs in shape today: the descriptor lists feature names as placement hints, and IN-003 puts them under requirements. To align under #746. | +| `placement.host_capabilities.network` | `spec.requirements.host_capabilities.network[].features` | Differs in shape today: the descriptor holds feature names only, and IN-003 also describes each network interface. To align under #746. | ### Where the descriptor goes further @@ -90,34 +103,56 @@ The descriptor covers areas that IN-003 doesn't cover yet: - **Artefact identity.** The chart and every image are pinned by digest, each release names its source commit and provenance record, and revocation comes from a revocation list. Question 6 in - [IN-003 issue #4](https://github.com/AMWA-TV/in-003/issues/4) asks whether - artefact identity belongs in IN-003 or in a separate Increment. + [IN-003 issue #4](https://github.com/AMWA-TV/in-003/issues/4) asked whether + artefact identity belongs in IN-003 or in a separate Increment. An AMWA + contributor replied on 2026-10-28 that identity is to be defined by the + ledger first. The descriptor keeps its own identity fields until that + definition exists. - **Software licence.** The required `software_licence` field holds the SPDX licence of the software the package ships. IN-003 has no licence field; it mentions a licence server only in prose. The word `licence` alone is kept for entitlements, such as licence-server seats, which the descriptor doesn't cover. -- **Closed content.** The schema rejects unknown keys everywhere. Question 1 - in the same issue asks whether IN-003 intends open content. +- **Closed content.** The schema rejects unknown keys in its fixed objects. + Some values are deliberately open and accept keys the schema doesn't list, + such as extension bodies, so a misspelled key inside one of them isn't + caught. The schema file defines exactly which values are open. In + the same issue, an AMWA contributor replied to question 1 on 2026-10-28 + that the IN-003 schema is as permissive as possible about fields and units + at this phase, because implementations vary. The contributor said they + didn't understand the question about unknown keys. We clarified that unknown + field names were the point and asked again on 2026-10-29. That specific + question is unanswered. The descriptor's fixed objects stay closed, so they + catch a misspelled field name early. - **Package-level checks.** The conformance tool checks things a schema can't, such as version identity with `Chart.yaml`, package-key collisions and revocation freshness. No question in issue #4 covers these yet. Question 2 in that issue, on where `host_capabilities` belongs, affects the -last two rows of the table. +last two rows of the table. AMWA is still investigating it upstream, so the +placement may move. ### Compatibility path -An IN-003 manifest is generated from the descriptor. That optional manifest -arrives with +Neither the IN-003 export nor the pinned-schema test exists yet. Both are +planned. + +The plan is to generate an IN-003 manifest from the descriptor. Fields that +differ in shape today, such as the frame rate, are to take the IN-003 shape +first, under +[dmfdeploy/dmfdeploy#746](https://github.com/dmfdeploy/dmfdeploy/issues/746), +so the export needs no conversion for them. That optional manifest is to +arrive with [dmfdeploy/dmfdeploy#637](https://github.com/dmfdeploy/dmfdeploy/issues/637), together with the descriptor field that points to it and the conformance check that compares the two. Until then the descriptor has no such field, and the schema rejects one. -Tests check the generated manifest against the IN-003 schema, fetched at the -pinned commit at test time. The IN-003 schema is never vendored into this -repository. + +A planned test is to check the generated manifest against the IN-003 schema, +fetched at the pinned commit at test time. The IN-003 schema is never to be +vendored into this repository. When IN-003 publishes a new revision, the pin moves in a pull request that -updates the mapping table and the export together. [dmfdeploy/dmfdeploy#746](https://github.com/dmfdeploy/dmfdeploy/issues/746) +updates the mapping table and, once it exists, the export together. +[dmfdeploy/dmfdeploy#746](https://github.com/dmfdeploy/dmfdeploy/issues/746) tracks this work.