AutoForge/docs/vehicle-profile-schema-v1.md

179 lines
9.9 KiB
Markdown

# Vehicle profile metadata and JSON schema version 1
## Scope and identity
Schema v1 is an in-memory interchange format for explicitly selected vehicle and
module metadata. It describes neither a real vehicle nor operational compatibility.
It contains no diagnostic commands, transport details, calibration values, firmware
bytes or programming authorization.
The top-level `schemaVersion` is the format version (`1`). It is separate from the
positive integer profile `revision`. A stable `profileIdentifier` can have multiple
saved revisions, each an immutable configuration snapshot. The catalog key is the
pair `(profileIdentifier, revision)`, compared ordinally without case sensitivity.
The profile contains a stable `vehicleIdentifier`; multiple profile revisions can
refer to the same vehicle. An exact unknown revision fails even if other revisions
exist.
All required strings are non-empty, not automatically trimmed, and may not have
leading/trailing whitespace. Identity uniqueness uses `OrdinalIgnoreCase`.
Custom module `role` and `operationIdentifier` strings are not closed enums.
Repeated roles are allowed when module-instance identifiers differ.
Optional model facts and hardware/software/firmware/calibration identifiers use
explicit JSON `null` to mean **unknown/not supplied**. They are never populated with
fabricated defaults. `modelYear` is null or a positive integer no greater than
9999. A calibration identifier is only a reference label; it does not contain
calibration data.
## Capability declaration contract
Each module may list zero or more operation declarations. Operation identifiers
are unique within that module using ordinal, case-insensitive comparison.
Declarations use exactly these v1 states:
| JSON status | Meaning of supplied metadata |
|---|---|
| `SUPPORTED` | A source declares support; no service, connection, permission or compatibility is implemented by this record. |
| `UNSUPPORTED` | A source explicitly declares the operation unsupported in the stated context. |
| `UNKNOWN` | A source explicitly reports uncertainty or unknown availability. |
| `INACCESSIBLE` | The source indicates the capability cannot currently be accessed; this is distinct from unsupported. |
| `RESTRICTED` | The source describes restrictions/limitations; it does not grant authorization. |
An absent declaration is not support. `ModuleInstance.GetCapability` returns an
explicit not-declared `UNKNOWN` assessment with a reason. The assessment's
`IsDeclared` distinguishes that result from a declared `UNKNOWN` entry. No status
causes the system to connect, discover a capability, execute an operation or
authorize a physical write.
## Provenance and applicability
Profile evidence records are local to one profile revision. Facts and declarations
reference evidence IDs instead of copying source claims. Every evidence record
supplies:
- A unique evidence identifier, classification, source reference and description.
- An applicability context with a required vehicle ID, optional applicable model
year, and optional profile ID + revision (both are required together or both
omitted).
- An optional module instance ID and optional hardware/software/firmware/calibration
identity context. These version-specific fields require a module ID.
- Optional confidence (`null` means unknown); numeric values must be finite and in
the inclusive range `[0, 1]`.
- Optional verification information, publication/retrieval timestamps and known
limitations. Timestamps are explicit source data; validation does not create
them from the current clock.
Classifications are `VERIFIED`, `UNVERIFIED`, `INFERRED` and `SYNTHETIC`. The
classification is supplied metadata and is not independently verified or promoted
by the application. Synthetic records are plainly labelled and include limitations.
Provenance does not grant permission.
Evidence IDs must resolve within the same profile revision. Vehicle, module and
capability evidence references must be applicable to their vehicle/module scope.
Evidence that names a profile revision, vehicle, model year, module or specific
identity must match under the documented identifier comparison when the profile
supplies that same fact. A null optional hardware/software/firmware/calibration
applicability identity means **no constraint was supplied**; it does not assert
that the corresponding module identity is null. A module-scoped record can name a
module while leaving all four optional identity constraints null. Each supplied
non-null constraint must match the corresponding known module identity using
ordinal case-insensitive comparison. A mismatch or a supplied constraint against
an unknown module identity rejects the profile; validation never infers or fills
that module identity. Version-specific constraints still require a module
instance ID, and dangling/wrong module, vehicle, profile/revision or conflicting
known model-year context rejects the profile. These rules apply identically to
module and capability evidence references and to direct Core construction and
JSON/service import.
### Publication and retrieval timestamps
`publishedAt` and `retrievedAt` accept explicit JSON `null` for unknown or exactly
this complete, offset-bearing ISO-8601 subset:
```text
YYYY-MM-DDTHH:mm:ss[.fraction](Z|+HH:mm|-HH:mm)
```
`YYYY` is a four-digit Gregorian year; `T` and `Z` are uppercase literals.
Seconds are required. The optional fraction is a decimal point followed by 1 to 7
ASCII digits (the .NET 100-nanosecond precision supported by `DateTimeOffset`).
The offset is required and is either `Z` for UTC or a signed numeric `HH:mm`
offset; valid offsets are limited to `-14:00` through `+14:00` in whole minutes.
Calendar/time values must be valid and representable with that offset. No
surrounding whitespace, date-only/time-only, missing seconds/year/offset, culture
date, zone name, comma fraction or extra fractional precision is accepted.
Timestamp input is parsed without local-time or current-date defaults. The parsed
wall time, fractional precision and supplied offset are retained semantically;
export uses the round-trip .NET timestamp representation.
Invalid timestamps produce a `VehicleProfileInterchangeException` at the exact
`publishedAt` or `retrievedAt` JSON path, before catalog registration.
## JSON document shape
The root object contains exactly:
- `schemaVersion`, `profileIdentifier`, `revision`
- `vehicle`
- `modules`
- `evidence`
`vehicle` contains its vehicle ID, required manufacturer/model, optional known
identity fields, and evidence references. Each evidence `applicability` object
contains the vehicle ID and nullable applicable model year, plus optional exact
profile-revision and module identity context. `modules` is an arbitrary list of
module instances with identity, role/name, optional IDs, evidence references, and
capability declarations. `evidence` contains the provenance records above.
Every schema-v1 property is required in the document; an optional fact is written
as an explicit `null`, and empty collections are written as `[]`. This makes a
missing value distinct from a known default. See the checked-in
[synthetic truck baseline](../src/tests/AutoForge.IntegrationTests/Fixtures/synthetic-truck-baseline.json),
[variant](../src/tests/AutoForge.IntegrationTests/Fixtures/synthetic-truck-variant.json)
and [alternate vehicle](../src/tests/AutoForge.IntegrationTests/Fixtures/synthetic-orchard-vehicle.json)
for complete examples.
The built-in .NET JSON parser rejects malformed JSON, comments/trailing commas,
duplicate or case-ambiguous object properties, missing properties, wrong types,
unknown properties and unsupported versions. Unknown properties are rejected in
v1 rather than silently discarded. Enum strings are uppercase exact tokens shown
above. Duplicate module IDs, capability operation IDs and evidence IDs are
rejected under ordinal case-insensitive comparison. Domain construction and JSON
import use the same invariants; there is no repair, downgrade, default provider,
random identifier, online lookup or hidden file write.
Future incompatible structure requires a new explicitly supported schema version
and a deliberate migration; v1 import never guesses or migrates future documents.
Failures use `VehicleProfileInterchangeException` with a JSON path and actionable
reason. Catalog duplicate and exact-revision misses use
`VehicleProfileCatalogException`. Full input JSON is not logged.
Step-02 and its Step-02A corrective work are worker-implemented and verified;
manual orchestrator acceptance remains pending. See the [Step-02A report](../prompts/Step-02A-Report.md)
for exact regression, build, test and native evidence.
## Application lifecycle and usage
The `Features/Vehicles/Profiles` Application slice exposes JSON import, list,
exact profile/revision select and export through `IVehicleProfileService`. Import
validates completely before atomic registration. The Client wires one in-memory
catalog for the process; imported data is not persisted and is cleared at app exit.
No database, global active vehicle, connection or AI model is involved.
The UI RCL's `/vehicle-profiles` page accepts explicit JSON paste, lists revisions,
requires a user selection, displays identity/capability/provenance/unknown
metadata, and presents a read-only schema-v1 export for the selected revision.
Import does not auto-select. An invalid or duplicate import does not replace
registered data or the current selection. The profile page is independent of the
existing explicit target resolver.
To try the synthetic path on Windows, start the native
[AutoForge.Client](../src/AutoForge.Client/AutoForge.Client.csproj), open
`/vehicle-profiles`, paste the checked-in baseline JSON and import it, then
explicitly select revision 1. Repeat with the variant as a separate import and
select revision 2 to inspect the distinct synthetic calibration identity. The
alternate fixture demonstrates a different inventory, custom module role and
operation. These records are test metadata only; they do not represent real
manufacturer definitions, services, simulation or working hardware support.