# Evidence and interpretation Canonical documentation: https://api.redlineautohaus.com/docs/uds/. API: `https://api.redlineautohaus.com/api/v1/uds`. The generated [OpenAPI contract](https://api.redlineautohaus.com/docs/uds/openapi.json) defines exact request fields. This guide explains their meaning. ## Unknown context is valid The smallest message requires a session, source record, stable observation key, client namespace, declared layer and payload representation. No VIN, vehicle, make, year, chassis, ECU family, supplier, endpoint, transport, bitrate or response is required. Omit unknown optional fields. Use explicit null only where the schema permits it. Empty catalog identifiers are invalid; a source that actually contains an empty value belongs in an evidence-backed assertion with `value_state: "empty"`. Never substitute dummy VINs, year zero, a generic manufacturer or a zero address for missing data. A genuinely observed zero remains a valid value when allowed by its field. On mutable metadata PATCH, omitted means unchanged and permitted null clears the field. Send the current `If-Match` version precondition. Raw evidence, payloads and immutable interpretation versions use new records/revisions rather than PATCH. ## Sources and evidence records Register the real source kind: original log, exported XML/JSON, capture file, screenshot, manual transcription, tool report or other. Tool/version, original name/path, clock and access restrictions are optional. A local path is a locator, never a hosted artifact. The API does not fetch arbitrary URLs or read client-selected filesystem paths. A source record needs a source, stable external key and a locator or nonempty inline excerpt. Line ranges are one-based inclusive; byte ranges are zero-based end-exclusive. Page/region, native event and labeled manual locators retain their source meaning. Include `source_order` as a decimal string where known; source order is distinct from receipt order. Manual typing and AI transcription must retain their actual origin. OCR is not exact binary extraction. If you have only a screenshot, do not claim an available original log. Sources can contribute to multiple sessions through explicit same-scope associations. Omitted source or source-record origin is stored as `unknown`. An extraction run must name the original source in its source set before its output can refer to that source's records. Merely uploading an artifact does not establish that an extraction occurred. Artifact registration also supports explicit `external` and `unavailable` availability with a reason. These are metadata states, not verified files: external references are never fetched automatically, and these records cannot be completed or used as available payload ranges. Original bytes, excerpts, filenames and paths require `uds:sensitive-read`; whole artifact access additionally requires `uds:artifact-read`. Metadata responses identify withheld raw fields. A reviewer may create an append-only `/redactions` derivative with a method and reason. It does not modify the original or grant access to it. ## Payload representations For `complete`, supply exactly one nonempty `payload_hex`, canonical `payload_base64`, or supported verified `artifact_range`. Inline hex is even-length, hex-only and contains no spaces. Hex is accepted case-insensitively and read back uppercase. The server decodes binary bytes and computes observed length and SHA-256. Any reported total must agree with a complete observation's actual length. For `partial`, supply nonempty segments with distinct ordinals and optional offsets. Offset zero means a known prefix; null or omitted offset means unknown position. Known segments cannot overlap or exceed a known total. Do not concatenate disjoint fragments into a fabricated complete message. Missing ranges and reported length are optional and need source support. ```json { "representation": "partial", "reason": "source_omitted_bytes", "segments": [ { "ordinal": 0, "offset_bytes": 0, "payload_hex": "623F06" } ] } ``` This example contains three observed bytes. An excerpt saying additional data was omitted does not supply those bytes or prove their total length. Do not zero-fill them. For `unavailable`, supply no byte payload and include a reason and source evidence describing what was unavailable. A missing response is normally no response message; a timeout is a capture event, not invented response bytes. Keep `uds_pdu`, `can_frame`, `transport_packet`, `unknown` and other declared layers distinct. Never strip headers or padding from original evidence as an undocumented cleanup step. Completeness, extraction quality, parse status, diagnostic status and transport outcome are different facts. ## Time, addresses and repeated identities Server receipt time is UTC. Source time may preserve raw text, timezone/offset, precision, clock domain and normalization method. Only supply normalized UTC if justified; never assume the server timezone for an ambiguous timestamp. Keep exact relative nanoseconds as a decimal string. Equal or backwards timestamps do not reorder the source. An address needs its reported namespace. A tool label such as `0x12` is not proof of a CAN ID. Claimed CAN addressing needs an explicit width/range; network peers and ECU identity remain separate. Preserve leading zeros and original TX/RX labels when adapter-relative direction is uncertain. An ECU observation may have family without supplier, supplier without family, or neither. Multiple endpoints with the same role are allowed. Address changes do not establish replacement, and an unchanged address does not establish the same physical ECU. Bench evidence does not require a vehicle. Partial VINs never authorize automatic identity merging. ## Facts, decoding and reviewed knowledge Use a valid scoped subject reference, namespaced property, value state, origin and evidence for a fact. Present values must match their declared type. Multiple conflicting facts remain distinct. Observation time and submission time are separate. A decoding records a submitted interpretation with producer/version or manual/AI origin, parse status and optional service/DID/routine/DTC fields. Repeated decoded items need ordinals; do not collapse multiple DIDs or software components into one value. New facts/definitions/decodings are unreviewed. Reviewer actions require separate permission and append review history. Definition applicability is `unknown` or explicitly `constrained`; missing constraints never mean universal compatibility. Reviewed knowledge still cannot transmit to a vehicle through this API. Corrections create a new occurrence/version plus an explicit supersession relationship. Preserve the original bytes, source location, producer and reason. A content hash groups identical byte content; it does not deduplicate two distinct source occurrences. Message searches for protocol, service or DID interpretations must select a decoding ID or a producer plus version. Conditions apply to the same submitted decoding, so results cannot silently combine incompatible interpretations. The API does not decode evidence to satisfy a search. Catalog search supports bounded name prefixes and advertised namespace/exact-identifier filters, not arbitrary JSON queries. ## Extensions Extensions are bounded, namespaced envelopes. For example, this synthetic unknown namespace carries source-reported text without asserting a recognized decoder: ```json { "extensions": { "example.capture": { "schema_version": "1.0", "data": { "source_label": "unresolved vendor label" } } } } ``` Unknown namespaces remain unvalidated. Known namespaces must use an advertised schema version; read capabilities/schema discovery first. Unknown top-level request keys are rejected. Do not submit arbitrary SQL, code, remote schemas or JSON-path expressions.