docs(spec): define normative keywords (RFC 2119 / RFC 8174)

[rishi-jat]

The specification uses terms like MUST, SHOULD, and MAY but did not define how they should be interpreted.

This PR adds a Normative Language section referencing RFC 2119 and RFC 8174 to clarify the meaning of these keywords and align the spec with standard drafting practices.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the clarity and precision of the specification by incorporating a dedicated section for normative language. By adopting the definitions from RFC 2119 and RFC 8174, the document now provides unambiguous guidance on the meaning of critical keywords, ensuring consistent interpretation and adherence to standard technical drafting practices.

Highlights

• Normative Language Definition: Introduced a new section to the specification that formally defines the interpretation of keywords such as "MUST", "SHOULD", and "MAY" by explicitly referencing RFC 2119 and RFC 8174.

Changelog

• docs/spec.md
  • Added a new "Normative Language" section.
  • Included references to RFC 2119 and RFC 8174 for keyword definitions.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a 'Normative Language' section to the specification, defining keywords like MUST and SHOULD by referencing RFC 2119 and RFC 8174. This is a good step towards aligning the spec with standard practices. My review includes a couple of suggestions to improve the document's usability and maintainability: making the RFC references clickable links and sorting the link definitions alphabetically.

[gemini-code-assist]

For better readability and to make it easier for readers to find the referenced RFCs, it's a good practice to make the RFC mentions clickable links. You've already added the link definitions at the end of the file.

Suggested change

	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
	"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
	"OPTIONAL" in this document are to be interpreted as described in
	RFC 2119 and RFC 8174 when, and only when, they appear in all capitals.
	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
	"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
	"OPTIONAL" in this document are to be interpreted as described in
	[RFC 2119][rfc2119] and [RFC 8174][rfc8174] when, and only when, they appear in all capitals.

[gemini-code-assist]

To improve maintainability, it's a good practice to keep reference link definitions sorted alphabetically.

Suggested change

	[image-spec]: https://github.com/opencontainers/image-spec/blob/main/spec.md#image-format-specification
	[rfc1952_2]: https://tools.ietf.org/html/rfc1952
	[rfc2119]: https://www.rfc-editor.org/rfc/rfc2119
	[rfc8174]: https://www.rfc-editor.org/rfc/rfc8174
	[tar-archive]: https://en.wikipedia.org/wiki/Tar_(computing)
	[image-manifest]: https://github.com/opencontainers/image-spec/blob/main/manifest.md
	[rfc8478]: https://tools.ietf.org/html/rfc8478
	[image-manifest]: https://github.com/opencontainers/image-spec/blob/main/manifest.md
	[image-spec]: https://github.com/opencontainers/image-spec/blob/main/spec.md#image-format-specification
	[rfc1952_2]: https://tools.ietf.org/html/rfc1952
	[rfc2119]: https://www.rfc-editor.org/rfc/rfc2119
	[rfc8174]: https://www.rfc-editor.org/rfc/rfc8174
	[rfc8478]: https://tools.ietf.org/html/rfc8478
	[tar-archive]: https://en.wikipedia.org/wiki/Tar_(computing)

[Copilot]

Pull request overview

Adds a Normative Language section to the model format specification so RFC 2119 / RFC 8174 keyword interpretations (MUST/SHOULD/MAY, etc.) are explicitly defined and consistent with common spec-writing practice.

Changes:

• Introduces a “Normative Language” section describing interpretation of uppercase normative keywords.
• Adds RFC 2119 and RFC 8174 link references to the spec’s reference list.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The Normative Language section mentions RFC 2119 / RFC 8174 as plain text, but the document otherwise uses reference-style links (e.g., [gzip][rfc1952_2]). Consider linking these as [RFC 2119][rfc2119] and [RFC 8174][rfc8174] to keep the style consistent and to make the added references actionable.

Suggested change

	RFC 2119 and RFC 8174 when, and only when, they appear in all capitals.
	[RFC 2119][rfc2119] and [RFC 8174][rfc8174] when, and only when, they appear in all capitals.

[Copilot]

The newly added reference definitions [rfc2119] and [rfc8174] are currently unused in the document. Either use them in the Normative Language section (preferred) or remove them to avoid unused link references / markdown-lint failures.

[rishi-jat]

/cc @chlins
/cc @aftersnow
/cc @bergwolf