# software.release.defs

> Published by [release.software](https://lexicon.garden/identity/did:plc:zimrxnxvvkwixvtkazpx3zfx)

✓ This is the authoritative definition for this NSID.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:zimrxnxvvkwixvtkazpx3zfx/software.release.defs)
- [Documentation](https://lexicon.garden/lexicon/did:plc:zimrxnxvvkwixvtkazpx3zfx/software.release.defs/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:zimrxnxvvkwixvtkazpx3zfx/software.release.defs/examples)

## Definitions

### `software.release.defs#blobArtifact`

**Type**: `object`

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.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `blob` | `blob` | Yes | 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. |
| `fileName` | `string` | Yes | 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. |
| `metadata` | `array` | No | 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` | `ref` → `#target` | No | Intended runtime target. Omission means compatibility is unspecified, not universal. |

### `software.release.defs#gitCommit`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `algorithm` | `string` | Yes | Git object hash algorithm. Consumers must report unsupported algorithms rather than treating the input as verified. |
| `digest` | `string` | Yes | 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. |

### `software.release.defs#gitRepository`

**Type**: `object`

A project's Git source location, independent of any particular forge. This describes development sources rather than a pinned release input.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `directory` | `string` | No | 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` | `string` | No | Fully qualified Git ref, such as refs/heads/main. Must satisfy Git ref syntax. May move over time. |
| `repository` | `string` (uri) | Yes | 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. |

### `software.release.defs#gitRevision`

**Type**: `object`

A pinned Git source input for a release. The commit is authoritative; an optional ref supplies context only.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `commit` | `ref` → `#gitCommit` | Yes |  |
| `directory` | `string` | No | 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` | `string` | No | 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. |
| `repository` | `string` (uri) | Yes | Cloneable repository URI, not an arbitrary forge page. Git's scp-like shorthand is not a URI. |

### `software.release.defs#target`

**Type**: `object`

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.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `architectures` | `array` | No | 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. |
| `os` | `string` | No | Intended runtime operating system. Use canonical known values where applicable, such as macos rather than darwin. Omission means unspecified, not support for every OS. |

## Raw Schema

```json
{
  "$type": "com.atproto.lexicon.schema",
  "defs": {
    "blobArtifact": {
      "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.",
      "properties": {
        "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.",
          "type": "blob"
        },
        "fileName": {
          "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,
          "minLength": 1,
          "type": "string"
        },
        "metadata": {
          "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.",
          "items": {
            "closed": false,
            "refs": [],
            "type": "union"
          },
          "type": "array"
        },
        "target": {
          "description": "Intended runtime target. Omission means compatibility is unspecified, not universal.",
          "ref": "#target",
          "type": "ref"
        }
      },
      "required": [
        "fileName",
        "blob"
      ],
      "type": "object"
    },
    "gitCommit": {
      "properties": {
        "algorithm": {
          "description": "Git object hash algorithm. Consumers must report unsupported algorithms rather than treating the input as verified.",
          "knownValues": [
            "sha1",
            "sha256"
          ],
          "minLength": 1,
          "type": "string"
        },
        "digest": {
          "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.",
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "algorithm",
        "digest"
      ],
      "type": "object"
    },
    "gitRepository": {
      "description": "A project's Git source location, independent of any particular forge. This describes development sources rather than a pinned release input.",
      "properties": {
        "directory": {
          "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.",
          "minLength": 1,
          "type": "string"
        },
        "ref": {
          "description": "Fully qualified Git ref, such as refs/heads/main. Must satisfy Git ref syntax. May move over time.",
          "type": "string"
        },
        "repository": {
          "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.",
          "format": "uri",
          "type": "string"
        }
      },
      "required": [
        "repository"
      ],
      "type": "object"
    },
    "gitRevision": {
      "description": "A pinned Git source input for a release. The commit is authoritative; an optional ref supplies context only.",
      "properties": {
        "commit": {
          "ref": "#gitCommit",
          "type": "ref"
        },
        "directory": {
          "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.",
          "minLength": 1,
          "type": "string"
        },
        "ref": {
          "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.",
          "type": "string"
        },
        "repository": {
          "description": "Cloneable repository URI, not an arbitrary forge page. Git's scp-like shorthand is not a URI.",
          "format": "uri",
          "type": "string"
        }
      },
      "required": [
        "repository",
        "commit"
      ],
      "type": "object"
    },
    "target": {
      "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": {
        "architectures": {
          "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.",
          "items": {
            "knownValues": [
              "amd64",
              "arm64",
              "386"
            ],
            "minLength": 1,
            "type": "string"
          },
          "minLength": 1,
          "type": "array"
        },
        "os": {
          "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.",
          "knownValues": [
            "linux",
            "macos",
            "windows",
            "android",
            "ios"
          ],
          "minLength": 1,
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "id": "software.release.defs",
  "lexicon": 1
}
```