Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarify mediaType and artifactType syntax #1182

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+60 −18
Open

Clarify mediaType and artifactType syntax #1182

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
7 changes: 2 additions & 5 deletions descriptor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ The following fields contain the primary properties that constitute a Descriptor
- **`mediaType`** *string*

This REQUIRED property contains the media type of the referenced content.
Values MUST comply with [RFC 6838][rfc6838], including the [naming requirements in its section 4.2][rfc6838-s4.2].
Values MUST comply with the [media type syntax](media-types.md#media-type-syntax).

The OCI image specification defines [several of its own MIME types](media-types.md) for resources defined in the specification.

Expand Down Expand Up @@ -56,7 +56,7 @@ The following fields contain the primary properties that constitute a Descriptor

This OPTIONAL property contains the type of an artifact when the descriptor points to an artifact.
This is the value of the config descriptor `mediaType` when the descriptor references an [image manifest](manifest.md).
If defined, the value MUST comply with [RFC 6838][rfc6838], including the [naming requirements in its section 4.2][rfc6838-s4.2], and MAY be registered with [IANA][iana].
If defined, the value MUST comply with the [media type syntax](media-types.md#media-type-syntax).

Descriptors pointing to [`application/vnd.oci.image.manifest.v1+json`](manifest.md) SHOULD include the extended field `platform`, see [Image Index Property Descriptions](image-index.md#image-index-property-descriptions) for details.

Expand Down Expand Up @@ -214,8 +214,5 @@ In the following example, the descriptor indicates the type of artifact it is re
[rfc4634-s4.1]: https://tools.ietf.org/html/rfc4634#section-4.1
[rfc4634-s4.2]: https://tools.ietf.org/html/rfc4634#section-4.2
[rfc4648-s4]: https://tools.ietf.org/html/rfc4648#section-4
[rfc6838]: https://tools.ietf.org/html/rfc6838
[rfc6838-s4.2]: https://tools.ietf.org/html/rfc6838#section-4.2
[rfc7230-s2.7]: https://tools.ietf.org/html/rfc7230#section-2.7
[sha256-vs-sha512]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/hsMw7cAwrZE
[iana]: https://www.iana.org/assignments/media-types/media-types.xhtml
5 changes: 1 addition & 4 deletions image-index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ For the media type(s) that this document is compatible with, see the [matrix][ma
- **`artifactType`** *string*

This OPTIONAL property contains the type of an artifact when the manifest is used for an artifact.
If defined, the value MUST comply with [RFC 6838][rfc6838], including the [naming requirements in its section 4.2][rfc6838-s4.2], and MAY be registered with [IANA][iana].
If defined, the value MUST comply with the [media type syntax](media-types.md#media-type-syntax).

- **`manifests`** *array of objects*

Expand Down Expand Up @@ -183,8 +183,5 @@ These values SHOULD match (or be similar to) their analog listed in [the Go Lang

[dag]: https://en.wikipedia.org/wiki/Merkle_tree
[go-environment2]: https://golang.org/doc/install/source#environment
[iana]: https://www.iana.org/assignments/media-types/media-types.xhtml
[matrix]: media-types.md#compatibility-matrix
[referrers-api]: https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers
[rfc6838]: https://tools.ietf.org/html/rfc6838
[rfc6838-s4.2]: https://tools.ietf.org/html/rfc6838#section-4.2
9 changes: 3 additions & 6 deletions manifest.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Unlike the [image index](image-index.md), which contains information about a set

This OPTIONAL property contains the type of an artifact when the manifest is used for an artifact.
This MUST be set when `config.mediaType` is set to the [empty value](#guidance-for-an-empty-descriptor).
If defined, the value MUST comply with [RFC 6838][rfc6838], including the [naming requirements in its section 4.2][rfc6838-s4.2], and MAY be registered with [IANA][iana].
If defined, the value MUST comply with the [media type syntax](media-types.md#media-type-syntax).
Implementations storing or copying image manifests MUST NOT error on encountering an `artifactType` that is unknown to the implementation.

- **`config`** *[descriptor](descriptor.md)*
Expand All @@ -53,7 +53,7 @@ Unlike the [image index](image-index.md), which contains information about a set
Manifests for container images concerned with portability SHOULD use one of the above media types.
Manifests for artifacts concerned with portability SHOULD use `config.mediaType` as described in [Guidelines for Artifact Usage](#guidelines-for-artifact-usage).

If the manifest uses a different media type than the above, it MUST comply with [RFC 6838][rfc6838], including the [naming requirements in its section 4.2][rfc6838-s4.2], and MAY be registered with [IANA][iana].
If the manifest uses a different media type than the above, it MUST comply with the [media type syntax](media-types.md#media-type-syntax).

To set an effectively null or empty config and maintain portability see the [guidance for an empty descriptor](#guidance-for-an-empty-descriptor) below, and `DescriptorEmptyJSON` of the reference code.

Expand Down Expand Up @@ -89,7 +89,7 @@ Unlike the [image index](image-index.md), which contains information about a set

Entries in this field will frequently use the `+gzip` types.

If the manifest uses a different media type than the above, it MUST comply with [RFC 6838][rfc6838], including the [naming requirements in its section 4.2][rfc6838-s4.2], and MAY be registered with [IANA][iana].
If the manifest uses a different media type than the above, it MUST comply with the [media type syntax](media-types.md#media-type-syntax).

See [Guidelines for Artifact Usage](#guidelines-for-artifact-usage) for other uses of the `layers`.

Expand Down Expand Up @@ -260,7 +260,4 @@ The decision tree below and the associated examples MAY be used to design new ar
_Implementers note:_ artifacts have historically been created without an `artifactType` field, and tooling to work with artifacts should fallback to the `config.mediaType` value.

[dag]: https://en.wikipedia.org/wiki/Merkle_tree
[iana]: https://www.iana.org/assignments/media-types/media-types.xhtml
[referrers-api]: https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers
[rfc6838]: https://tools.ietf.org/html/rfc6838
[rfc6838-s4.2]: https://tools.ietf.org/html/rfc6838#section-4.2
18 changes: 16 additions & 2 deletions media-types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,17 @@ The following media types identify a ["Layer" with distribution restrictions](la
- `application/vnd.oci.image.layer.nondistributable.v1.tar+gzip`: ["Layer", as a tar archive with distribution restrictions](layer.md#gzip-media-types) compressed with [gzip][rfc1952]
- `application/vnd.oci.image.layer.nondistributable.v1.tar+zstd`: ["Layer", as a tar archive with distribution restrictions](layer.md#zstd-media-types) compressed with [zstd][rfc8478]

## Media Type Syntax

Media types values MUST comply with [RFC 6838][rfc6838], including the [naming requirements in its section 4.2][rfc6838-s4.2], and MAY be registered with [IANA][iana].
Media types values MUST have a top-level type and subtype name, separated by a `/`, without any parameters.

The following regular expression may be used to validate media types:

```regexp
^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]{0,126}/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]{0,126}$
```
Comment on lines +24 to +30
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moving this to a common section seems good (instead of repeating it over and over again), but I'm not convinced we have a good reason to limit further than what the RFC specifies? To put that another way, what do we gain from adding extra restrictions on top of the RFC itself?

We've previously discussed (and don't explicitly say anything about) case sensitivity too, as another example: https://oci.dag.dev/?image=tianon/test:sPoNgEbOb

I don't think this is great, but the spec has historically pointed to the RFC as-is. I think it's totally fair for us to say our media types/spec-specified objects shouldn't have parameters, but something about telling other artifact authors they also cannot do so feels off.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We were pointing directly to section 4.2, so there's a case to be made by some implementations that we had already excluded parameters that were defined in 4.3 (ECR rejects these manifests today). And schema/defs-descriptor.json almost defined this as a restriction if there wasn't a bug in the regexp.

A big fear for allowing this for fields like artifactType includes the referrers query with an artifactType filter. Should that allow parameters in the query, or should all responses with any parameter be returned if no parameter is included? That part of the spec gets a bit undefined without this limit.


## Media Type Conflicts

[Blob](image-layout.md) retrieval methods MAY return media type metadata.
Expand Down Expand Up @@ -86,5 +97,8 @@ The following figure shows how the above media types reference each other:
[Descriptors](descriptor.md) are used for all references.
The image-index being a "fat manifest" references a list of image manifests per target platform. An image manifest references exactly one target configuration and possibly many layers.

[rfc1952]: https://tools.ietf.org/html/rfc1952
[rfc8478]: https://tools.ietf.org/html/rfc8478
[iana]: https://www.iana.org/assignments/media-types/media-types.xhtml
[rfc1952]: https://tools.ietf.org/html/rfc1952
[rfc6838]: https://tools.ietf.org/html/rfc6838
[rfc6838-s4.2]: https://tools.ietf.org/html/rfc6838#section-4.2
[rfc8478]: https://tools.ietf.org/html/rfc8478
2 changes: 1 addition & 1 deletion schema/defs-descriptor.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
"mediaType": {
"id": "https://opencontainers.org/schema/image/descriptor/mediaType",
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9!#$&-^_.+]{0,126}/[A-Za-z0-9][A-Za-z0-9!#$&-^_.+]{0,126}$"
"pattern": "^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]{0,126}/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]{0,126}$"
},
"digest": {
"description": "the cryptographic checksum digest of the object, in the pattern '<algorithm>:<encoded>'",
Expand Down
13 changes: 13 additions & 0 deletions schema/descriptor_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -259,6 +259,19 @@ func TestDescriptor(t *testing.T) {
fail: true,
},

// expected failure: artifactType does not match pattern (parameters not allowed)
{
descriptor: `
{
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"artifactType": "foo/star.bar;version=1.0",
"size": 7682,
"digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270"
}
`,
fail: true,
},

// expected success: data field is present and has base64 content
{
descriptor: `
Expand Down
24 changes: 24 additions & 0 deletions schema/manifest_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -336,6 +336,30 @@ func TestManifest(t *testing.T) {
`,
fail: false,
},

// invalid artifactType value
{
manifest: `
{
"schemaVersion": 2,
"mediaType" : "application/vnd.oci.image.manifest.v1+json",
"artifactType": "application/vnd.example+type;revision=1.5",
"config": {
"mediaType": "application/vnd.oci.empty.v1+json",
"size": 2,
"digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a"
},
"layers": [
{
"mediaType": "application/vnd.example+type;revision=1.5",
"size": 675598,
"digest": "sha256:9d3dd9504c685a304985025df4ed0283e47ac9ffa9bd0326fddf4d59513f0827"
}
]
}
`,
fail: true,
},
} {
r := strings.NewReader(tt.manifest)
err := schema.ValidatorMediaTypeManifest.Validate(r)
Expand Down