# Broker Bridge Context Exchange JSON Schemas — Draft Release Notes (Version 202601)

## Summary
This is the first **draft** release of the JSON Schema package for **Broker Bridge Context Exchange**. The schemas are translated from the existing **EDIFACT** standard into **JSON**, with the primary goal of enabling **rapid implementation**, early integration testing, and **stakeholder feedback**.

This release focuses exclusively on the **Broker Bridge** scope. A broader standardization effort (beyond Broker Bridge) is ongoing; this package is an early deliverable intended to align approach and expectations as soon as possible.

## Status and intended use
- **Status:** Draft
- **Intended use:** **Testing and feedback** (not production-ready / stability not guaranteed)
- **Compatibility:** Changes may occur in upcoming iterations based on feedback and findings.

## Package format and contents
- **Distribution:** ZIP archive
- **Included directories:**
  - `payloads/` — example JSON payloads
  - `schemas/` — main schemas
  - `shared/` - subschemas
    - `lists/` - value lists (values are described with their XML tag equivalent)
    - `lists/official/` — official value lists, provided with more descriptive explanations
    - `primitives/` — shared primitive schemas (percentage, year)
  - `.vscode/` — includes `settings.json` to link example payloads to schemas in VSCode for validation
 
## JSON Schema dialect
- **JSON Schema version:** **2020-12**
- **Important note:** Early analysis started with **Draft-07**, but it was replaced by **2020-12** in order to support **stricter validation behavior for sub-schemas**.

## Scope of this release

### Main schemas included
- `insuredBuildingAndAssiocatedObjectsData.202601.json`
- `insuredHouseholdPrivateData.202601.json`
- `insuredIndividualPersonData.202601.json`
- `insuredMotorisedVehicleAndDriverData.202601.json`
- `insuredTrailerData.202601.json`
- `policyHolderOrCoPolicyHolderData.202601.json`

This release also includes **all associated value lists**. Only the value lists associated with the provided schemas are included in this draft.

### Coverage priorities
- Primary focus for this first draft:
  - `policyHolderOrCoPolicyHolderData`
  - `insuredMotorisedVehicleAndDriverData`
- The package represents **complete messages/objects** within the Broker Bridge scope.

### Shared / factored components
This release introduces initial **factorization** to improve reuse and reduce duplication, including:
- Shared base schema: `commonInsuredObjectData_V1.json`  
  Used as a common foundation for:
  - `insuredBuildingAndAssiocatedObjectsData.202601.json`
  - `insuredHouseholdPrivateData.202601.json`
  - `insuredIndividualPersonData.202601.json`
  - `insuredMotorisedVehicleAndDriverData.202601.json`
  - `insuredTrailerData.202601.json`
- Smaller shared schemas (examples): **address**, **name**
- Value lists are referenced heavily via `$ref`

## Versioning approach

> We aligned our 202601 version of the JSON Schemas with the current EDIFACT 202601 standard, with one major change regarding NACEBEL code handling. Codes from the 2008 list are no longer supported, and it is now possible to provide up to five codes from the 2025 list. This is intended to avoid forcing additional developments on this topic when moving to 202701.

- **Release version:** `202601` (aligned with the EDIFACT norm versioning). 
- **Schema `$id`:**
  - Main schemas use the same norm version (currently `202601`)
  - Value lists follow their own list versioning (`V1`, `V2`, `V3`, …)
- **Note:** While a formal lifecycle policy is not yet validated, the following statuses are being considered: `supported`, `deprecated`, `sunset`, `experimental`.

## Validation rules and conventions
- **Naming convention:** `camelCase`
- **Alignment with EDIFACT:**
  - Schema structures reflect EDIFACT constraints “as-is” (**no more, no less**)
  - List values are expressed in **camelCase**
  - Official lists under `shared/lists/official/` are provided with **more descriptive explanations**
- **Strictness / locking:** Schemas are designed to be **locked down** to reflect current EDIFACT constraints. Where improvements are possible, stakeholder feedback is expected. A specific Excel file that lists the changes to the mapping of XML keys that were inconsistent or could be improved is available.
- **Conditional validation:** No conditional logic (`if/then/else`) is implemented at this stage.

## How to use (quick validation workflow)
There is no prescribed deployment model: consumers may integrate and host the schemas according to their own infrastructure and architecture.

To validate quickly using the provided examples:
1. Open the ZIP contents in **VSCode**
2. Ensure the `.vscode/settings.json` is present and picked up by VSCode
3. Open files in `payloads/` — VSCode will associate payloads with the relevant schemas and report validation issues inline

> Note: At this stage, validation has been performed primarily using the tooling integrated in **VSCode**.

## Known limitations
- The **data model is preserved** from EDIFACT; this draft does not attempt to improve or redesign it.
- Factorization is introduced to make the schemas easier to maintain and consume, but the underlying model remains the same.
- Cross-field validation rules may exist conceptually, but are not expressed via conditionals in this release.

## Out of scope
- Changes to the EDIFACT norm itself
- Objects/messages not related to **Broker Bridge**
- Broader, cross-domain normalization beyond the Broker Bridge scope (work in progress)

## Feedback requested
We are specifically looking for feedback on:
- Schema **coherence and consistency**
- Appropriateness of **property locking / strictness**
- Cleanliness and usability of the **package structure**
- Alignment with **business expectations**
- Any inconsistencies found compared to the EDIFACT norm (will be addressed through version increments)

## Next iteration
A next iteration will be published after receiving stakeholder feedback. (Internal expectation: end of March, TBD.)

## Contact
Please send feedback by email or in OpenProject
Maintainer: **Datassur**
