Add CAMARA release metadata schemas (Issue #337)

[hdamker]

What type of PR is this?

enhancement/feature

What this PR does / why we need it:

Implements JSON Schema definitions and validation for CAMARA release metadata files as specified in the Release Workflow and Metadata Concept document.

This PR adds:

• JSON Schema Draft 7 definitions for release-plan.yaml and release-metadata.yaml
• 5 example files covering key scenarios (new repo, multi-API, RC preparation, patch release, generated metadata)
• Python validation script with schema and semantic checks
• Comprehensive README documentation
• Schema harmonization with master-metadata-schema.yaml for release-collector compatibility

Schema harmonization (2nd commit):

• Aligns release-metadata.yaml structure with master-metadata-schema.yaml from project-administration
• Enables release-collector to extract all needed data from release tags
• Key changes:
  • Added repository_name field (immutable repository identifier)
  • Renamed release_number → release_tag (consistent naming)
  • Updated release_date to ISO 8601 datetime format (UTC)
  • Renamed apis[].name → api_name (leading identifier)
  • Added apis[].title field (from OpenAPI info.title)
  • Removed apis[].main_contacts from release-metadata (not immutable)

Concept document updates:

• Updated examples in CAMARA-Release-Workflow-and-Metadata-Concept.md to reflect harmonized field names
• Updated terminology table (release_number → release_tag)
• Updated release_date format to ISO 8601 datetime

Additional change: Renamed status to release_type in release-metadata schema to prevent ambiguity with workflow status or lifecycle status.

All 5 examples validate successfully against the schemas.

Which issue(s) this PR fixes:

Fixes #337

Special notes for reviewers:

• Schemas use JSON Schema Draft 7 specification
• Extensibility enabled (additionalProperties allowed) for future field additions
• Field names align with master-metadata-schema.yaml from project-administration
• Validation script auto-detects schema type (release-plan vs release-metadata)
• Python script provided (JavaScript migration planned for Phase 1B)
• Small updates to concept document examples to use harmonized field names

Changelog input

Add JSON Schema definitions for release-plan.yaml and release-metadata.yaml with validation tooling and comprehensive examples. Schema harmonization with master-metadata-schema.yaml enables release-collector integration.

Additional documentation

- artifacts/metadata-schemas/README.md: Complete usage documentation
- artifacts/metadata-schemas/schemas/: JSON Schema definitions
- artifacts/metadata-schemas/examples/: 5 scenario examples
- Updated CAMARA-Release-Workflow-and-Metadata-Concept.md examples

[hdamker]

@camaraproject/release-management_maintainers @camaraproject/release-management_codeowners

Please review this PR carefully and as soon as possible as it creates the base for our release process automation (see the dependencies within the implementation plan in #338).

For the alignment with the Release Collector workflow I have created already camaraproject/project-administration#52

[rartych]

Is there any specific need to use http://json-schema.org/draft-07/schema# over the latest https://json-schema.org/draft/2020-12/schema JSON Schema definitions ?

[hdamker]

Is there any specific need to use http://json-schema.org/draft-07/schema# over the latest https://json-schema.org/draft/2020-12/schema JSON Schema definitions ?

The question is more if there is a specific need to use the latest. "draft-07 is the safer and fully sufficient choice; moving to 2020-12 mainly brings theoretical advantages and future extensibility, but at the cost of more careful tooling validation and possible friction for consumers".

[hdamker]

@camaraproject/release-management_maintainers Any further comments? Would be good if we can finalize / approve the schemata within the ReleaseManagement call on Tuesday Dec 2nd.

[albertoramosmonagas]

LGTM

[tanjadegroot]

first comments set

[hdamker]

Thank you @tanjadegroot for the thorough review! It helped a lot to improve the schemata.

Here's a summary of the decision I have taken on each topic - hope that fits for you:

---

Terminology

Topic 1: "maturity" vs "status"
Agreed to use "API status" instead of "maturity" in prose to avoid confusion with repository maturity (Sandbox/Incubating/Graduated). Enum values remain unchanged.

Topic 2: "suffix" vs "extension"
Agreed to use "extension" instead of "suffix" for version pre-release identifiers (e.g., -alpha.1, -rc.2).

---

Field Naming

Topic 3: release_readiness rename
Finally agreed to rename release_readiness → target_release_type. After further analysis, the field semantics are about what release type we're targeting for the NEXT release, not about achieved validation state. This aligns with the existing target_version pattern (now renamed target_api_version for consistency) - all three target_* fields answer "what are we targeting in the next release?" for different aspects:

• target_api_version → which version?
• target_release_type → which release type? (e.g., M3 rc, M4 public for meta-releases)
• target_api_status → which API status?

Note: In release-metadata.yaml (generated file), the field remains release_type (not target_release_type) since by that point it's the actual release type, not a target.

CI validates that the repository content supports the declared target.

Topic 4: api_status rename
Agreed to rename api_status → target_api_status for consistency with the target_* pattern. The field declares the API status for the next release, and CI validates that the API definition meets the requirements for that status level.

Additional proposed changes:

• Renamed planned → draft (better conveys WIP with basic validation)
• Removed unchanged from enum - CI will implicitly lock APIs when target_api_version equals an already-released public version

Topic 5: Version field renames
Agreed to rename version to api_version in the apis[] section of release-metadata for consistency.

Additionally renamed target_version to target_api_version in release-plan.yaml to align with the api_* naming pattern used for other API properties (api_name, api_version).

Topic 6: Dependencies format
Agreed to rename fields to commonalities_release and identity_consent_management_release since values are release numbers (r4.2), not versions. The release-metadata format remains r4.2 (1.0.1) with resolved version added during release (at least as long there is a repository wide version in Commonalities)

---

Meta-Release Handling

Topic 7: meta_release optionality
Added a new release_track property with enum [none, sandbox, meta-release] to make the intent explicit:

• release_track: none - no release planned
• release_track: sandbox - release outside meta-release cycle
• release_track: meta-release - participating in a meta-release (requires meta_release field)

This clarifies semantics: meta_release only exists when the repository participates in a meta-release.

Note: Initially named release_scope, renamed to release_track to avoid conflict with the "scope" terminology used in API repositories for their target release scope.

---

Patterns and Enums

Topic 8: release_tag pattern
Corrected pattern to ^r[1-9]\d*\.[1-9]\d*$ (excluding zeros per existing guideline). Example changed from r5.0 to r5.3.

Topic 9: pre-release-alpha enum value
Agreed to add pre-release-alpha. Also dropped the generic pre-release:

• pre-release-alpha: All APIs at alpha or better, mix of alpha/rc allowed. Public only for previously released APIs (no new public versions in pre-release).
• pre-release-rc: All changed APIs at rc status.

Topic 10: title vs api_status in release-metadata
Decided to keep title (from OpenAPI info.title). No need to add api_status - the status is encoded in the version extension (-alpha.N, -rc.N, or none for public).

---

Example Files

Topic 11: File naming
Agreed to rename:

• 02-multi-api-mixed-maturity.yaml → 02-multi-api-mixed-status.yaml
• 05-generated-metadata.yaml → 05-generated-release-metadata.yaml

Topic 12: Example 03 clarification
Kept filename 03-rc-preparation.yaml. Updated comments to clarify it shows the pre-release-rc stage before public release.

---

Documentation

Topics 14-18:
Updated README, concept document, and validation script with all above changes. Added source information to release-metadata field descriptions (derived from release-plan vs generated during release).

---

Summary of Changes

Topic	Decision
"maturity" → "status"	Agreed
"suffix" → "extension"	Agreed
release_readiness rename	Agreed (target_release_type)
api_status rename	Agreed (target_api_status)
planned → draft	Proposed change
Remove unchanged	Proposed change (implicit lock)
version → api_version	Agreed
Dependency fields rename	Agreed (xxx_release)
Add release_track	Proposed new field
release_tag pattern	Corrected (no zeros)
Add pre-release-alpha	Agreed
Drop pre-release	Proposed change
Keep title	Agreed
Example renames	Agreed
target_version → target_api_version	Proposed change

[hdamker]

Open Questions

Dropping api_ prefix from API properties?

With the addition of target_api_version, we now have several API properties with an api_ prefix: api_name, api_version, target_api_version, target_api_status.

Since these properties are already nested under apis[], the api_ prefix is somewhat redundant. Would it make sense to simplify to just name, version, target_version, target_status?

This would reduce verbosity while the context (apis[] array) still makes it clear these are API-level properties. Thoughts?

Should release_tag be auto-calculated to reduce manual updates?

Currently, release-plan.yaml requires specifying the exact release_tag (e.g., r3.1). Consequence: If we need a second Release Candidate (r3.2), we must manually update release-plan.yaml on main to bump the tag, even if the API target_version plan (e.g., 1.0.0) remains identical. This creates unnecessary friction and commits for every RC iteration.

Proposal: Change the schema to accept a Release Cycle (e.g., r3) instead of a specific tag. The automation would then:

1. Read release_cycle: r3.
2. Check existing tags in git (e.g., finds r3.1).
3. Auto-calculate the next incremental tag (r3.2).

Benefit: The release-plan.yaml would remain persistent and static throughout the entire pre-release phase (RC1 -> RC2 -> RC3), mirroring the efficient behavior we already have for API versions.

[tanjadegroot]

Open Questions

Dropping api_ prefix from API properties?

With the addition of target_api_version, we now have several API properties with an api_ prefix: api_name, api_version, target_api_version, target_api_status.

Since these properties are already nested under apis[], the api_ prefix is somewhat redundant. Would it make sense to simplify to just name, version, target_version, target_status?

This would reduce verbosity while the context (apis[] array) still makes it clear these are API-level properties. Thoughts?

I would prefer to keep the api_ part as not very long and consoistent with definition elswhere (api_name, api-version in Commonalities dicumentation)

Should release_tag be auto-calculated to reduce manual updates?

Currently, release-plan.yaml requires specifying the exact release_tag (e.g., r3.1). Consequence: If we need a second Release Candidate (r3.2), we must manually update release-plan.yaml on main to bump the tag, even if the API target_version plan (e.g., 1.0.0) remains identical. This creates unnecessary friction and commits for every RC iteration.

Proposal: Change the schema to accept a Release Cycle (e.g., r3) instead of a specific tag. The automation would then:

1. Read release_cycle: r3.
2. Check existing tags in git (e.g., finds r3.1).
3. Auto-calculate the next incremental tag (r3.2).

Benefit: The release-plan.yaml would remain persistent and static throughout the entire pre-release phase (RC1 -> RC2 -> RC3), mirroring the efficient behavior we already have for API versions.

why would we need at all the release tag in the plan if you can find and generate the latest_ Can it no be derived from the api-status ? Today the release tracker does not require to specify the release tag (or cycle) - that would avoid introducing the release cycle concept.

[tanjadegroot]

Thank you @tanjadegroot for the thorough review! It helped a lot to improve the schemata.

Here's a summary of the decision I have taken on each topic - hope that fits for you:

Thanks very much Herbert for the summary and for taking into account all these comments.
I also agree with your additional proposals.

I would have one more comment:
should we make it explicit that the target_api_version is the public version of the API: so rename it to target_public_api_version ?
This may help avoid that pêople would put x.y.z-rc.1 in that field. but I guess the validation would catch that anyway.

[tanjadegroot]

still some points to check

[tanjadegroot]

I presume the release date is automatically generated ? but when exactly ? is it the date/time of the release PR merge ?

however the schema validator checks this before the merge I suppose:
... if 'release_date' in repo and 'src_commit_sha' in repo: ...

so it has to be set before the validation, and cannot be after the release PR commit ?

I probably missed something (I hope) ...

Also, in the example for "Fall26", logically it should say "2026-..." (iso "2025-... ) ?

[hdamker]

See #339 (comment) for an explanation how release_date and src_commit_sha are generated. release_date is more or less the time of the last commit done by the automation on the release branch (after the release PR is merged). During the release PR both fields will be validated to be null.

The example is updated.

[tanjadegroot]

Same comment as for release_date. "generated during release creation" seems too late as the file has to go into the release.

[hdamker]

See #339 (comment) for explanation.

Your question has triggered the simplification ... with subsequent updates of the release branch from main branch, the calculation of this value would become complex.

[hdamker]

Thank you @tanjadegroot for the second round of thorough review! Your questions about the metadata timing and terminology helped clarify important aspects of the release workflow, especially Phase 4 (automated release creation).

Terminology & Field Name Consistency

• Agreed to rename all occurrences of patch-release → maintenance-release, 7 files updated
• Agreed to rename title → api_title for consistency with other API properties, 3 files updated and created Release Collector: Update field names to api_version and api_title project-administration#69 (api_version was anyway necessary to change there)

Generated Metadata Timing and Workflow

Regarding the questions about when release_date and src_commit_sha are generated, and how validation works if they're populated after the release PR the proposal is to implement a two-phase workflow with immutable release branches as the initial implementation. That is a simplification compared to the current concept which allowed to merge from main during the lifetime of the release branch.

Phase 1: Release Branch Preparation (with PR review)

1. Automation creates release branch from main/maintenance HEAD
2. Generates release-metadata.yaml with:
   • release_date: null (will be set at finalization)
   • src_commit_sha: null (will be set at finalization)
   • Other fields derived from release-plan.yaml
3. Release PR is created for review
4. Immutable release branch principle:
   • Release branch content is immutable after creation
   • Exception: CHANGELOG.md entries may be added/updated
   • If API corrections needed: abandon release (close PR, delete branch), fix main, retrigger

Phase 2: Finalization (after PR merge)

1. Automation triggers on release PR into release branch merge
2. Populates final metadata:
   • release_date: Current UTC timestamp
   • src_commit_sha: HEAD SHA from base branch at branch creation time
3. Creates "release commit": chore: finalize release metadata for rX.Y
4. Creates git tag pointing to this release commit
5. CI builds and publishes artifacts
6. GitHub Release is created

Files updated

1. Schema descriptions (release-metadata-schema.yaml):

   • release_date: Explains null during prep, populated at finalization
   • src_commit_sha: Explains immutable branch approach and calculation

2. Workflow documentation (CAMARA-Release-Workflow-and-Metadata-Concept.md):

   • Step 3 (Review): Added abandon-and-retrigger process for API corrections
   • Step 4 (Tag and Generate): Comprehensive two-phase workflow explanation
   • Step 5d (new): Notes release branches are temporary, can be deleted after tag
   • Appendix ("Updating Release Branch from Main"): Marked for future consideration with clear note:

     This section describes a forward-merge approach that is deferred for future consideration.
     The initial implementation uses immutable release branches.

[tanjadegroot]

All OK for the round 2 comments but sorry, I ended up with another batch.
please skip as you see fit.
per your guidance I should not approve this yet

[tanjadegroot]

I think the "sandbox" value would be impacted by the new name for "independent" release e.g. step/intermediate/solo/individual

"indepedent" would work for me as well (as indeed this has started to be used and not sure that people use "Independent Sandbox" very often, rather just "Sandbox")

individual would be good as opposed to the meta-release being a grouped release (though we do not really use that term).

the change will impact the example files

[hdamker]

We can change this when we concluded the discussion. I will then change consistently across the files.

Current candidate none, independent, meta-release

[hdamker]

Update: have done the change to none, independent, meta-release in 5251ef0

[tanjadegroot]

Question, but could be ignored, as "none" would imply to ignore the release tag I guess.

• if there is a (target) release_tag given, should the target_release_type not be at least 'pre-release-alpha' ? (as none - No release planned or not ready yet)
• or should the (target) release_tag value initially be "r-.-" or empty.
• or if we consider the first pre-release is always at least alpha, then do we need the "none" value ?

[tanjadegroot]

logically (but maybe cosmetic) I would put the target_release_type before the (target) release tag.

[hdamker]

in the beginning the repository is not ready for any release (no API definition), so 'pre-release-alpha' would be invalid. My proposal is to set the line initially to

target_release_tag: null # replace with r1.1 for first release

[tanjadegroot]

logically I would put the release_type before the release_tag

[hdamker]

I keep the current order. Every release_type has a release_tag and the release_tag is the first thing I see after the repository in GitHub -- it is together with the repository the identifier of the release.

[tanjadegroot]

online 437 below what is a Post-Release PR ? do we need it ?

[hdamker]

Yes, we do. It is the same as described in step 5.1.

[hdamker]

@tanjadegroot The changes for your third round of comments are within the commits b0c6de5, 1764119, and 09386f6. Details are in the commit descriptions.

One point is open: the value which replace the "sandbox" track. See my comment on this conversation.

One additional change which I have decided in 50e45ad: I removed the meta-release property from the release-metadata.yaml as I'm convinced that this is not immutable already at the time of the release commit and tagging. Definitely not for pre-releases, but also not for public releases (M4 -> M5). We won't be able to change this affiliation any more if it is in the release itself. Instead we should define the relationship between a repository rx release series and a concrete meta-release in a configuration file and enrich the generated reports with that.

[hdamker]

@camaraproject/release-management_codeowners We should get this merged soon. Further fine-tuning of descriptions is possible later, also updates of the schema itself (with some effort).

[hdamker]

One point is open: the value which replace the "sandbox" track. See my comment on this conversation.

@tanjadegroot that's done now as well in 5251ef0