Add specs of TR endorsement as markdown.

Bug: 351967413
Change-Id: I861b5078431090bac686797b9a21dd2d98e22d20

docs/tr/endorsement_v1.md

@@ -1,3 +1,84 @@
-# Endorsement V1
+# Endorsement Specification V1
 
-WIP: Landing page for endorsement V1 in-toto statement.
+Transparent Release (TR) endorsement statements are represented and serialized
+as [JSON] objects.
+
+## Schema
+
+Endorsements are [in-toto statement]s (V1 only) with a custom predicate. In the following
+example, only the subject, the timestamps and the claim types are variable.
+
+```jsonc
+{
+  "_type": "https://in-toto.io/Statement/v1",
+  "subject": [
+    {
+      "name": "oak_orchestrator",
+      "digest": {
+        "sha256": "8c938394c5962194d1449ee17b4db5fdf5a78729b38ebacf26de9bed4027e351",
+      },
+    },
+  ],
+  "predicateType": "https://project-oak.github.io/oak/tr/endorsement/v1",
+  "predicate": {
+    "issuedOn": "2024-10-07T06:44:22.459000Z",
+    "validity": {
+      "notBefore": "2024-10-07T06:44:22.459000Z",
+      "notAfter": "2025-10-07T06:44:22.459000Z",
+    },
+    "claims": [
+      {
+        "type": "https://github.com/project-oak/oak/blob/main/docs/tr/claim/85483.md",
+      },
+    ],
+  },
+}
+```
+
+## Fields
+
+`_type` _string representing a [TypeURI], required_
+
+> Identifier for the schema of the in-toto statement. Always
+> `https://in-toto.io/Statement/v1` for the present endorsements. Only V1
+> in-toto statements are supported.
+
+`subject` _array of [ResourceDescriptor] objects, required_
+
+> Fully follows the [in-toto statement] specification.
+
+`predicateType` _string representing a [TypeURI], required_
+
+> Identifies the schema of the predicate. Always
+> `https://project-oak.github.io/oak/tr/endorsement/v1` for the present
+> endorsements.
+
+The `predicate` includes the following fields:
+
+`predicate.issuedOn` _string representing a [Timestamp], required_
+
+> Specifies when the endorsement was issued.
+
+`predicate.validity.notBefore` _string representing a [Timestamp], required_
+
+> Specifies when the endorsement starts to be valid.
+
+`predicate.validity.notAfter` _string representing a [Timestamp], required_
+
+> Specifies when the endorsement ceases to be valid.
+
+`predicate.claims` _array of claim objects, optional_
+
+> A claim identifies one or more properties the endorser asserts about the
+> endorsed subject. Encoded claims have just one `type` field which is a string
+> representing a [TypeURI]. The choice of identifier and its meaning are up to
+> the endorser.
+
+[JSON]: https://www.json.org/json-en.html
+[in-toto statement]: https://in-toto.io/Statement/v1
+[ResourceDescriptor]:
+  https://github.com/in-toto/attestation/blob/main/spec/v1/resource_descriptor.md
+[TypeURI]:
+  https://github.com/in-toto/attestation/blob/main/spec/v1/field_types.md#TypeURI
+[Timestamp]:
+  https://github.com/in-toto/attestation/blob/main/spec/v1/field_types.md#timestamp