179 lines
9.9 KiB
Markdown
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.
|