---
# System prepended metadata

title: SCITT Feed Structure

---

## Feed Hierarchy and Properties

SCITT [defines a feed](https://ietf-wg-scitt.github.io/draft-ietf-scitt-architecture/draft-ietf-scitt-architecture.html#name-terminology) as:
> an identifier chosen by the Issuer for the Artifact. For every Issuer and Feed, the Registry on a Transparency Service contains a sequence of Signed Statements about the same Artifact. In COSE, Feed is a dedicated header attribute in the protected header of the Envelope.

To provide more structure, we have a tracking issue: [Refine Definition of Feed #11](https://github.com/ietf-wg-scitt/draft-ietf-scitt-architecture/issues/11)

This document outlines a potential structure for feeds, enabling submissions and queries around a specific platform and version of an artifact.

_Although these may be header properties, rather than a hierarchical structure._

The proposed structure provides:
- For each platform/architecture a series of compatible versions are released.
- For each version, a series of statements are made.
- Statements for a specific platform/architecture and version would not apply to another platform/architecture and version.
- Each variant must be treated uniquely.


~~~~ aasvg
 .---------------.
| feed identifier |
 '----+----------'
      |  .---------------------.
      |'+ platform/architecture |
      |  '-+-------------------'
      |    |  .-------.
      |     '+ version |
      |       '-+-----'
      |         |  .-----------.
      |          '+ sub-version |
      |            '-+---------'
      |              |  +-------------+
      |               '-+ contentType |
      |                 +-------------+
      |  .---------------------.
       '+ platform/architecture |
         '-+-------------------'
           |  .-------.
            '+ version |
              '-+-----'
                |  .-----------.
                 '+ sub-version |
                   '-+---------'
                     |  +-------------+
                      '-+ contentType |
                        +-------------+
~~~~

There's an intentional structure as the consumer of the `netlog:v8` package running on `linux/amd64` server has no need to query information about the mac (`darwin/amd64`) version.
The ability to query for updates to a specific `versioned` `package` on a specific `platform/architecture` enables a consumer to target just what they need.

~~~~ aasvg
 .-----------.
| net-monitor |
 '----+------'
      |   .------------.
      |'-+ darwin/amd64 |
      |   '-+----------'
      |     |   .--.
      |      '-+ v1 |
      |         '-+'
      |           |   .----.
      |            '-+ v1.1 |
      |               '-+--'
      |                 |  +-------+
      |                  '-+ ctype |
      |                    +-------+
      |
      |   .-----------.
      |'-+ linux/amd64 |
      |   '-+---------'
      |     |   .--.
      |      '-+ v1 |
      |         '-+'
      |           |   .----.
      |            '-+ v1.1 |
      |               '-+--'
      |                 |  +----------------------------------+
      |                 |'-+ ctype: example/sbom              |
      |                 |  | created: 2023-01-01T16:00:00.00Z |
      |                 |  +----------------------------------+
      |                 |
      |                 |  +----------------------------------+
      |                 |'-+ ctype: example/scan-result       |
      |                 |  | created: 2023-01-01T16:00:00.00Z |
      |                 |  +----------------------------------+
      |                 |
      |                 |  +----------------------------------+
      |                  '-+ ctype: example/scan-result       |
      |                    | created: 2023-01-03T10:30:00.00Z |
      |                    +----------------------------------+
      |
      |   .--------------.
       '-+ linux/arm64/v8 |
          '-+------------'
            |  .--.
            '-+ v1 |
               '-+'
                 |  +----------------------------------+
                  '-+ ctype: example/sbom              |
                    | created: 2023-01-03T10:30:00.00Z |
                    +----------------------------------+
~~~~


### Multiple Content Types Issued by Multiple Identities

For each `version` of a `platform/architecture` package, a series of statements may be made.
Note that the same statement (content type) may be made by different identities (issuers), or updated statements may be made as new information is discovered.

```output
net-monitor
└─ linux/amd64
   └─── v1
```

| Issuer | Type | Time Created |
| - | - | - |
| wabbit-networks |`SPDX SBOM`| 2023-01-01T16:00:00.00Z |
| wabbit-networks |`CycloneDX SBOM` | 2023-01-01T16:00:00.00Z |
| wabbit-networks |`SDL Compliance` | 2023-01-01T16:00:00.00Z |
| wabbit-networks |`Provenance` | 2023-01-01T16:00:00.00Z |
| wabbit-networks |`GitBom` | 2023-01-01T16:00:00.00Z |
| cogswell-defender |`Scan Result` | 2023-01-01T16:00:00.00Z |
| cogswell-defender |`Scan Result` | 2023-01-03T10:30:00.00Z |
| cogswell-defender |`Scan Result` | ... |
| clair |`Scan Result` | 2023-04-01T18:30:00.00Z |
| cogswell-defender |`Scan Result` | 2023-04-02T17:00:00.00Z |
| wabbit-networks |`Patch Version Notification` | 2023-04-03T15:30:00.00Z |
| clair |`Scan Result` | 2023-04-03T18:00:00.00Z |
| cogswell-defender |`Scan Result` | 2023-04-03T18:00:00.00Z |


### Conceptual Feeds

A feed is a resource, identified by a URL.

Resources can be expressed in multiple content types.

`application/scitt.feed+cbor` is mandatory to support.

`scitt.feed+cbor` encodes a structure for paging a potentially infinite list.

Although these examples are YAML the actual representation would be CBOR.

Generic example, a feed identifies a list of receipts.

GET https://ts.example/feeds/42 --accept application/yaml

```yaml
# todo paging...
items:
 - id: https://ts.example/signed-statements/receipts/0
   
   # consider the feed to be of receupts for artifacts that have been signed with cose sign1    
   # contentId: https://vendor.example/packages/cool-software/sbom/receipt
   contentType: application/scitt.receipt+cbor
   content: base64url encoded receipt (`application/scitt.receipt+cbor`)

   # consider that implementations might augment responses with artifacts by reference or by value. 
   # payloadId: https://vendor.example/packages/cool-software/sbom
   # payloadType: application/spdx+json
   # payload: base64url encoded payload

 - id: https://ts.example/signed-statements/receipts/1
```

Slightly more structure...

A feed exposes a list of receipts, filtered to specific elements.

GET https://ts.example/feeds/by-payload-content-type/application/spdx+json
GET https://ts.example/feeds/by-signed-statement-issuer/did:vendor.example:ci-server:53
GET https://ts.example/feeds/by-purl/pkg:docker/debian@sha256:2f04d3d33b6027bb74ecc81397abe780649ec89f1a2af18d7022737d0482cefe

Non software domain examples:

GET https://ts.example/feeds/facility/geohash
GET https://ts.example/feeds/facility/geohash/imports
GET https://ts.example/feeds/facility/geohash/exports

GET https://ts.example/feeds/address/tokens
GET https://ts.example/feeds/address/transactions

GET https://ts.example/feeds/physical-address/insurance-policies
GET https://ts.example/feeds/human-identifier/insurance-policies

GET https://ts.example/feeds/vehicle-identifier/titles
GET https://ts.example/feeds/vehicle-identifier/insurance
GET https://ts.example/feeds/vehicle-identifier/speeding-tickets

Seems there are actually 2 concepts hidden in 1 here...

"Feed" as a topic committed to by the issuer of the receipt.

For example `application/spdx+json` for `pkg:docker/debian@sha256:2f04d3d33b6027bb74ecc81397abe780649ec89f1a2af18d7022737d0482cefe` by `docker.transparency.example`

^ You will see the Feed for the first case in a COSE Sign1 protected header.

"Feed" as an aggregation over witnessed receipts related to "various related topics"

For example "all the receipts" for `pkg:docker/debian@sha256` (any hash, all content types) by `docker.transparency.example`.

^ You won't ever see the Feed for the second case in a COSE Sign1 protected header.