# 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.