software.release.defs
software.release.defs{
"lexicon": 1,
"id": "software.release.defs",
"defs": {
"blobArtifact": {
"type": "object",
"description": "A named downloadable file stored as a blob in the manifest publisher's PDS. Consumers MUST verify downloaded bytes against the blob CID. Target metadata is optional and describes coarse runtime compatibility, not installation instructions.",
"required": [
"fileName",
"blob"
],
"properties": {
"fileName": {
"type": "string",
"minLength": 1,
"description": "Suggested download filename, not a path. MUST NOT contain slashes, backslashes, or control characters, and MUST NOT be dot or dot-dot. Consumers MUST handle it as untrusted input and ensure it is safe for the destination filesystem. Filenames do not define target compatibility.",
"maxLength": 255
},
"blob": {
"type": "blob",
"accept": [
"*/*"
],
"description": "The artifact bytes. The blob reference supplies the content CID, MIME type, and size. No artifact-specific size limit is imposed; hosting services may impose their own limits."
},
"target": {
"type": "ref",
"ref": "#target",
"description": "Intended runtime target. Omission means compatibility is unspecified, not universal."
},
"metadata": {
"type": "array",
"items": {
"type": "union",
"refs": [],
"closed": false
},
"description": "Typed ecosystem-specific metadata fragments. Metadata supplements core artifact fields and MUST NOT override or contradict them. Consumers may display or offer downloads of artifacts with unknown fragment types, but MUST NOT assume those fragments impose no additional requirements for automated installation. Unknown fragment types do not establish compatibility or suitability for automated installation."
}
}
},
"httpArtifact": {
"type": "object",
"description": "A named downloadable file hosted at an external HTTPS URL. The URL locates the file; the CID identifies its bytes. Consumers MUST verify both CID and size before executing, installing, or extracting the file. Consumers fetching URLs MUST apply appropriate network access restrictions, including to redirects.",
"required": [
"fileName",
"url",
"cid",
"size"
],
"properties": {
"fileName": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Suggested download filename, not a path. MUST NOT contain slashes, backslashes, or control characters, and MUST NOT be dot or dot-dot. Consumers MUST handle it as untrusted input and ensure it is safe for the destination filesystem. Filenames do not define target compatibility."
},
"url": {
"type": "string",
"format": "uri",
"description": "HTTPS download URL. Publishers SHOULD use durable URLs without embedded credentials or expiring access tokens. Redirects MUST remain HTTPS. A change in the bytes served does not change the artifact's declared identity."
},
"cid": {
"type": "string",
"format": "cid",
"description": "Content identifier for the complete artifact file bytes, after decoding HTTP transfer and content encodings but before unpacking any artifact archive. MUST use CIDv1, lowercase base32 encoding, the raw codec (0x55), and a 32-byte SHA-256 (0x12) or BLAKE3 (0x1e) digest, following DASL (https://dasl.ing/cid.html) or BDASL (https://dasl.ing/bdasl.html). Consumers MUST support SHA-256 and MAY support BLAKE3. Publishers SHOULD use SHA-256 for broad interoperability. Consumers MUST NOT treat unsupported hash algorithms as verified. A BLAKE3 CID alone does not supply the proofs or transport needed for verified streaming or range retrieval."
},
"size": {
"type": "integer",
"minimum": 0,
"description": "Expected size in bytes of the file identified by the CID, after decoding HTTP content encodings but before unpacking any artifact archive."
},
"mimeType": {
"type": "string",
"minLength": 1,
"description": "Optional publisher-declared media type of the artifact file."
},
"target": {
"type": "ref",
"ref": "#target",
"description": "Intended runtime target. Omission means compatibility is unspecified, not universal."
},
"metadata": {
"type": "array",
"items": {
"type": "union",
"refs": [],
"closed": false
},
"description": "Typed ecosystem-specific metadata fragments. Metadata supplements core artifact fields and MUST NOT override or contradict them. Consumers may display or offer downloads of artifacts with unknown fragment types, but MUST NOT assume those fragments impose no additional requirements for automated installation. Unknown fragment types do not establish compatibility or suitability for automated installation."
}
}
},
"target": {
"type": "object",
"description": "Coarse runtime compatibility for an artifact, not its build host. This is not a complete compatibility guarantee: OS versions, ABI, libc, and CPU features may impose additional requirements. Unknown values MUST NOT be treated as compatibility matches by consumers that do not understand them.",
"properties": {
"os": {
"type": "string",
"minLength": 1,
"knownValues": [
"linux",
"macos",
"windows",
"android",
"ios"
],
"description": "Intended runtime operating system. Use canonical known values where applicable, such as macos rather than darwin. Omission means unspecified, not support for every OS."
},
"architectures": {
"type": "array",
"minLength": 1,
"items": {
"type": "string",
"minLength": 1,
"knownValues": [
"amd64",
"arm64",
"386"
]
},
"description": "Supported runtime CPU architectures, with no duplicates. Each entry is an alternative supported architecture, not a simultaneous requirement. Architecture identifiers follow Go GOARCH naming as adopted by the OCI Image Specification's platform.architecture field (https://github.com/opencontainers/image-spec/blob/v1.0.2/image-index.md). Publishers SHOULD use canonical identifiers where applicable, such as amd64, arm64, and 386 rather than x86_64, aarch64, and x86. Omission means unspecified, not architecture-independent."
}
}
},
"gitRepository": {
"type": "object",
"description": "A project's Git source location, independent of any particular forge. This describes development sources rather than a pinned release input.",
"required": [
"repository"
],
"properties": {
"repository": {
"type": "string",
"format": "uri",
"description": "Cloneable repository URI, such as an HTTPS or ssh:// clone URI, not an arbitrary forge page. Git's scp-like shorthand is not a URI."
},
"directory": {
"type": "string",
"minLength": 1,
"description": "Repository-relative directory using slash separators. No leading or trailing slash, backslashes, empty segments, or dot or dot-dot segments. Omit for the repository root."
},
"ref": {
"type": "string",
"description": "Fully qualified Git ref, such as refs/heads/main. Must satisfy Git ref syntax. May move over time."
}
}
},
"gitRevision": {
"type": "object",
"description": "A pinned Git source input for a release. The commit is authoritative; an optional ref supplies context only.",
"required": [
"repository",
"commit"
],
"properties": {
"repository": {
"type": "string",
"format": "uri",
"description": "Cloneable repository URI, not an arbitrary forge page. Git's scp-like shorthand is not a URI."
},
"commit": {
"type": "ref",
"ref": "#gitCommit"
},
"ref": {
"type": "string",
"description": "Fully qualified Git ref, such as refs/tags/v1.2.3. Must satisfy Git ref syntax. This is descriptive context and never overrides the pinned commit."
},
"directory": {
"type": "string",
"minLength": 1,
"description": "Repository-relative directory using slash separators. No leading or trailing slash, backslashes, empty segments, or dot or dot-dot segments. Omit for the repository root."
}
}
},
"gitCommit": {
"type": "object",
"required": [
"algorithm",
"digest"
],
"properties": {
"algorithm": {
"type": "string",
"knownValues": [
"sha1",
"sha256"
],
"minLength": 1,
"description": "Git object hash algorithm. Consumers must report unsupported algorithms rather than treating the input as verified."
},
"digest": {
"type": "string",
"minLength": 1,
"description": "Full lowercase hexadecimal commit object ID, never abbreviated. Exactly 40 characters for sha1 or 64 for sha256. This hashes the Git commit object, not the source archive bytes."
}
}
}
}
}A named downloadable file stored as a blob in the manifest publisher's PDS. Consumers MUST verify downloaded bytes against the blob CID. Target metadata is optional and describes coarse runtime compatibility, not installation instructions.
- fileNamestringRequiredminLength:1maxLength:255
- Suggested download filename, not a path. MUST NOT contain slashes, backslashes, or control characters, and MUST NOT be dot or dot-dot. Consumers MUST handle it as untrusted input and ensure it is safe for the destination filesystem. Filenames do not define target compatibility.
- blobblobRequiredaccept:*/*
- The artifact bytes. The blob reference supplies the content CID, MIME type, and size. No artifact-specific size limit is imposed; hosting services may impose their own limits.
- targetrefOptionalref:#target
- Intended runtime target. Omission means compatibility is unspecified, not universal.
- metadataarrayOptional
- Typed ecosystem-specific metadata fragments. Metadata supplements core artifact fields and MUST NOT override or contradict them. Consumers may display or offer downloads of artifacts with unknown fragment types, but MUST NOT assume those fragments impose no additional requirements for automated installation. Unknown fragment types do not establish compatibility or suitability for automated installation.
A named downloadable file hosted at an external HTTPS URL. The URL locates the file; the CID identifies its bytes. Consumers MUST verify both CID and size before executing, installing, or extracting the file. Consumers fetching URLs MUST apply appropriate network access restrictions, including to redirects.
- fileNamestringRequiredminLength:1maxLength:255
- Suggested download filename, not a path. MUST NOT contain slashes, backslashes, or control characters, and MUST NOT be dot or dot-dot. Consumers MUST handle it as untrusted input and ensure it is safe for the destination filesystem. Filenames do not define target compatibility.
- urlstringuriRequired
- HTTPS download URL. Publishers SHOULD use durable URLs without embedded credentials or expiring access tokens. Redirects MUST remain HTTPS. A change in the bytes served does not change the artifact's declared identity.
- cidstringcidRequired
- Content identifier for the complete artifact file bytes, after decoding HTTP transfer and content encodings but before unpacking any artifact archive. MUST use CIDv1, lowercase base32 encoding, the raw codec (0x55), and a 32-byte SHA-256 (0x12) or BLAKE3 (0x1e) digest, following DASL (https://dasl.ing/cid.html) or BDASL (https://dasl.ing/bdasl.html). Consumers MUST support SHA-256 and MAY support BLAKE3. Publishers SHOULD use SHA-256 for broad interoperability. Consumers MUST NOT treat unsupported hash algorithms as verified. A BLAKE3 CID alone does not supply the proofs or transport needed for verified streaming or range retrieval.
- sizeintegerRequired
- Expected size in bytes of the file identified by the CID, after decoding HTTP content encodings but before unpacking any artifact archive.
- mimeTypestringOptionalminLength:1
- Optional publisher-declared media type of the artifact file.
- targetrefOptionalref:#target
- Intended runtime target. Omission means compatibility is unspecified, not universal.
- metadataarrayOptional
- Typed ecosystem-specific metadata fragments. Metadata supplements core artifact fields and MUST NOT override or contradict them. Consumers may display or offer downloads of artifacts with unknown fragment types, but MUST NOT assume those fragments impose no additional requirements for automated installation. Unknown fragment types do not establish compatibility or suitability for automated installation.
Coarse runtime compatibility for an artifact, not its build host. This is not a complete compatibility guarantee: OS versions, ABI, libc, and CPU features may impose additional requirements. Unknown values MUST NOT be treated as compatibility matches by consumers that do not understand them.
- osstringOptionalminLength:1knownValues:linux, macos, windows, android, ios
- Intended runtime operating system. Use canonical known values where applicable, such as macos rather than darwin. Omission means unspecified, not support for every OS.
- architecturesarrayOptionalminLength:1items.minLength:1items.knownValues:amd64, arm64, 386
- Supported runtime CPU architectures, with no duplicates. Each entry is an alternative supported architecture, not a simultaneous requirement. Architecture identifiers follow Go GOARCH naming as adopted by the OCI Image Specification's platform.architecture field (https://github.com/opencontainers/image-spec/blob/v1.0.2/image-index.md). Publishers SHOULD use canonical identifiers where applicable, such as amd64, arm64, and 386 rather than x86_64, aarch64, and x86. Omission means unspecified, not architecture-independent.
A project's Git source location, independent of any particular forge. This describes development sources rather than a pinned release input.
- repositorystringuriRequired
- Cloneable repository URI, such as an HTTPS or ssh:// clone URI, not an arbitrary forge page. Git's scp-like shorthand is not a URI.
- directorystringOptionalminLength:1
- Repository-relative directory using slash separators. No leading or trailing slash, backslashes, empty segments, or dot or dot-dot segments. Omit for the repository root.
- refstringOptional
- Fully qualified Git ref, such as refs/heads/main. Must satisfy Git ref syntax. May move over time.
A pinned Git source input for a release. The commit is authoritative; an optional ref supplies context only.
- repositorystringuriRequired
- Cloneable repository URI, not an arbitrary forge page. Git's scp-like shorthand is not a URI.
- commitrefRequiredref:#gitCommit
- —
- refstringOptional
- Fully qualified Git ref, such as refs/tags/v1.2.3. Must satisfy Git ref syntax. This is descriptive context and never overrides the pinned commit.
- directorystringOptionalminLength:1
- Repository-relative directory using slash separators. No leading or trailing slash, backslashes, empty segments, or dot or dot-dot segments. Omit for the repository root.
- algorithmstringRequiredminLength:1knownValues:sha1, sha256
- Git object hash algorithm. Consumers must report unsupported algorithms rather than treating the input as verified.
- digeststringRequiredminLength:1
- Full lowercase hexadecimal commit object ID, never abbreviated. Exactly 40 characters for sha1 or 64 for sha256. This hashes the Git commit object, not the source archive bytes.