docs(spec): define normative keywords (RFC 2119 / RFC 8174) #176
+9
−0
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -4,6 +4,13 @@ The specification defines an open standard for packaging and distribution of Art | |||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| The goal of this specification is to outline a blueprint and enable the creation of interoperable solutions for packaging and retrieving AI/ML models by leveraging the existing OCI ecosystem, thereby facilitating efficient model management, deployment and serving in cloud-native environments. | ||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| ## Normative Language | ||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| 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. | ||||||||||||||||||||||||||||||
|
There was a problem hiding this comment. 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
|
||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| ## Use Cases | ||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| - An OCI Registry can store and manage AI/ML model artifacts, making model versions, metadata, and parameters both retrievable and easily displayed. | ||||||||||||||||||||||||||||||
|
|
@@ -178,6 +185,8 @@ Once the model artifact is stored in an OCI registry, the container runtime (e.g | |||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
| [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 | ||||||||||||||||||||||||||||||
|
Comment on lines
+188
to
+189
There was a problem hiding this comment. 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. |
||||||||||||||||||||||||||||||
| [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 | ||||||||||||||||||||||||||||||
|
Comment on lines
186
to
192
Contributor
There was a problem hiding this comment. To improve maintainability, it's a good practice to keep reference link definitions sorted alphabetically.
Suggested change
|
||||||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.