9.9 KiB
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 (
nullmeans 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:
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,revisionvehiclemodulesevidence
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,
variant
and alternate vehicle
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 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, 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.