From f8b5be6aefaa35af79dbfcafca56a75cd291d493 Mon Sep 17 00:00:00 2001 From: Nicolas Buffon Date: Wed, 11 Dec 2024 15:10:35 +0100 Subject: [PATCH] schema: new version 2.1.0 for DENM **Note: This new version contains breaking changes (2, 3.2, 3.3, 5.1, 5.2)** 1. Add references to the document used to write this schema Comment has been added to the TS (Technical specification) file reference to indicate that it is prefered to solve conflicts that may be present against the EN (European standard) one 2. Mutualized the following two object types in `$defs` - information_quality - delta_reference_position 3. `management_container` 1. Clarify reference_time vs. detection_time by adding comments (cf. gh#223) 2. Rename `relevance_distance` to `awareness_distance` 3. Removed `confidence` field Instead, `event_position` object now carries its confidence 4. `situation_container` 1. Added new optionnal field `event_zone` 2. Added new optionnal field `linked_denms` 3. Added new optionnal field `event_end` 5. `location_container` 1. Removed `confidence` field Instead, both `event_speed` and `event_position_heading` are now object carrying both value and its confidence 2. Renamed `traces` to `detection_zones_to_event_position` 6. Fixed few typos Signed-off-by: Nicolas Buffon --- schema/denm/denm_schema_2-1-0.json | 579 +++++++++++++++++++++++++++++ 1 file changed, 579 insertions(+) create mode 100644 schema/denm/denm_schema_2-1-0.json diff --git a/schema/denm/denm_schema_2-1-0.json b/schema/denm/denm_schema_2-1-0.json new file mode 100644 index 00000000..c87032f0 --- /dev/null +++ b/schema/denm/denm_schema_2-1-0.json @@ -0,0 +1,579 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://Orange-OpenSource.github.io/its-client/schema/denm", + "description": "DENM JSON schema", + "$references": [ + { + "$comment": "This technical specification file (TS) is hereby considered right over the European standard one (EN); meaning that for any difference that may be present between those files this schema will prefer what is defined in the technical specification", + "name": "DENM TS 103 831", + "version": "2.2.1", + "url": "https://forge.etsi.org/rep/ITS/asn1/denm_ts103831/-/tree/v2.2.1" + }, + { + "name": "DENM EN 302 637-3", + "version": "1.3.1", + "url": "https://forge.etsi.org/rep/ITS/asn1/denm_en302637_3/-/tree/v1.3.1" + } + ], + "type": "object", + "additionalProperties": false, + "required": [ + "message_type", + "source_uuid", + "timestamp", + "version", + "message" + ], + "properties": { + "message_type": { + "type": "string", + "description": "Type of the message carried in 'message' property", + "const": "denm" + }, + "source_uuid": { + "type": "string", + "examples": [ + "UNKNOWN", + "CCU6", + "MEC2" + ] + }, + "timestamp": { + "type": "integer", + "description": "Unit: millisecond. The timestamp when the message was generated since Unix Epoch (1970/01/01)", + "examples": [ + 1574778515424 + ], + "minimum": 1514764800000, + "maximum": 1830297600000 + }, + "version": { + "type": "string", + "description": "JSON message format version", + "const": "2.0.0" + }, + "path": { + "type": "array", + "description": "List of ordered elements root source of the message", + "minItems": 1, + "items": { + "type": "object", + "required": [ + "position", + "message_type" + ], + "properties": { + "position": { + "type": "object", + "required": [ + "latitude", + "longitude", + "altitude" + ], + "properties": { + "latitude": { + "type": "integer", + "description": "Unit: 0.1 microdegree. oneMicrodegreeNorth (10), oneMicrodegreeSouth (-10), unavailable(900000001)", + "default": 900000001, + "minimum": -900000000, + "maximum": 900000001 + }, + "longitude": { + "type": "integer", + "description": "Unit: 0.1 microdegree. oneMicrodegreeEast (10), oneMicrodegreeWest (-10), unavailable(1800000001)", + "default": 1800000001, + "minimum": -1800000000, + "maximum": 1800000001 + }, + "altitude": { + "type": "integer", + "description": "Unit: 0.01 meter. referenceEllipsoidSurface(0), oneCentimeter(1), unavailable(800001)", + "default": 800001, + "minimum": -100000, + "maximum": 800001 + } + } + }, + "message_type": { + "description": "root message type source of the element", + "enum": [ + "denm", + "cam", + "cpm", + "po" + ] + } + } + } + }, + "message": { + "type": "object", + "required": [ + "protocol_version", + "station_id", + "management_container" + ], + "properties": { + "protocol_version": { + "type": "integer", + "description": "version of the ITS message and/or communication protocol", + "minimum": 0, + "maximum": 255, + "examples": [ + 1 + ] + }, + "station_id": { + "type": "integer", + "description": "identifier for an ITS-S", + "minimum": 0, + "maximum": 4294967295, + "examples": [ + 1, + 42 + ] + }, + "management_container": { + "type": "object", + "required": [ + "action_id", + "detection_time", + "reference_time", + "event_position" + ], + "properties": { + "action_id": { + "type": "object", + "required": [ + "originating_station_id", + "sequence_number" + ], + "properties": { + "originating_station_id": { + "type": "integer", + "description": "identifier of an its station", + "minimum": 0, + "maximum": 4294967295 + }, + "sequence_number": { + "type": "integer", + "description": "The sequence number is set each time a new DENM is created. It is used to differentiate from events detected by the same ITS-S.", + "minimum": 0, + "maximum": 65535 + } + } + }, + "detection_time": { + "type": "integer", + "description": " Time at which the event is detected by the originating ITS-S. For the DENM repetition, this DE shall remain unchanged.", + "minimum": 0, + "maximum": 4398046511103, + "$comment": "Remains the same on repetition; updated if any value changed in the payload, meaning sequence_number remains unchanged but anything else has been updated", + "$comment": "Unit: millisecond since ETSI epoch (2004/01/01, so 1072915200000); utcStartOf2004(0), oneMillisecAfterUTCStartOf2004(1)" + }, + "reference_time": { + "type": "integer", + "description": "Time at which a new DENM, an update DENM or a cancellation DENM is generated.", + "minimum": 0, + "maximum": 4398046511103, + "$comment": "Unit: millisecond since ETSI epoch (2004/01/01, so 1072915200000). utcStartOf2004(0), oneMillisecAfterUTCStartOf2004(1)", + "$comment": "Different for each message, even for repetition" + }, + "termination": { + "type": "integer", + "description": "isCancellation(0), isNegation (1)", + "minimum": 0, + "maximum": 1 + }, + "event_position": { + "type": "object", + "required": [ + "latitude", + "longitude", + "altitude", + "confidence" + ], + "properties": { + "latitude": { + "type": "integer", + "description": "Unit: 0.1 microdegree. oneMicrodegreeNorth (10), oneMicrodegreeSouth (-10), unavailable(900000001)", + "default": 900000001, + "minimum": -900000000, + "maximum": 900000001 + }, + "longitude": { + "type": "integer", + "description": "Unit: 0.1 microdegree. oneMicrodegreeEast (10), oneMicrodegreeWest (-10), unavailable(1800000001)", + "default": 1800000001, + "minimum": -1800000000, + "maximum": 1800000001 + }, + "altitude": { + "type": "integer", + "description": "Unit: 0.01 meter. referenceEllipsoidSurface(0), oneCentimeter(1), unavailable(800001)", + "default": 800001, + "minimum": -100000, + "maximum": 800001 + }, + "confidence": { + "$comment": "mandatory on ETSI specification, FIXME?", + "type": "object", + "properties": { + "position_confidence_ellipse": { + "$comment": "mandatory on ETSI specification, FIXME?", + "type": "object", + "properties": { + "semi_major_confidence": { + "$comment": "if not provided, 'semi_major_confidence' = 4095 (unavailable)", + "type": "integer", + "description": "oneCentimeter(1), outOfRange(4094), unavailable(4095)", + "default": 4095, + "minimum": 0, + "maximum": 4095 + }, + "semi_minor_confidence": { + "$comment": "if not provided, 'semi_minor_confidence' = 4095 (unavailable)", + "type": "integer", + "description": "oneCentimeter(1), outOfRange(4094), unavailable(4095)", + "default": 4095, + "minimum": 0, + "maximum": 4095 + }, + "semi_major_orientation": { + "$comment": "if not provided, 'semi_major_orientation' = 3601 (unavailable)", + "type": "integer", + "description": "wgs84North(0), wgs84East(900), wgs84South(1800), wgs84West(2700), unavailable(3601)", + "default": 3601, + "minimum": 0, + "maximum": 3601 + } + } + }, + "altitude": { + "$comment": "if not provided, 'altitude' = 15 (unavailable)", + "type": "integer", + "description": "alt-000-01 (0), alt-000-02 (1), alt-000-05 (2), alt-000-10 (3), alt-000-20 (4), alt-000-50 (5), alt-001-00 (6), alt-002-00 (7), alt-005-00 (8), alt-010-00 (9), alt-020-00 (10), alt-050-00 (11), alt-100-00 (12), alt-200-00 (13), outOfRange (14), unavailable (15)", + "default": 15, + "minimum": 0, + "maximum": 15 + } + } + } + } + }, + "awareness_distance": { + "type": "integer", + "description": "radius of the circular awareness area, with centre at the event position or at any of the event history points", + "minimum": 0, + "maximum": 7, + "$comment": "lessThan50m(0), lessThan100m(1), lessThan200m(2), lessThan500m(3), lessThan1000m(4), lessThan5km(5), lessThan10km(6), over10km(7)" + }, + "relevance_traffic_direction": { + "type": "integer", + "description": "Traffic direction along which the receiving ITS-S may encounter the event", + "minimum": 0, + "maximum": 3, + "$comment": "allTrafficDirections(0), upstreamTraffic(1), downstreamTraffic(2), oppositeTraffic(3)" + }, + "validity_duration": { + "type": "integer", + "description": "Duration after which the DENM can be considered invalid", + "minimum": 0, + "maximum": 86400, + "default": 600, + "$comment": "Unit: second. timeOfDetection(0), oneSecondAfterDetection(1)" + }, + "transmission_interval": { + "type": "integer", + "description": "Unit: millisecond. oneMilliSecond(1), tenSeconds(10000)", + "minimum": 1, + "maximum": 10000 + }, + "station_type": { + "$comment": "if not provided, 'station_type' = 0 (unknown)", + "description": "unknown(0), pedestrian(1), cyclist(2), moped(3), motorcycle(4), passengerCar(5), bus(6), lightTruck(7), heavyTruck(8), trailer(9), specialVehicles(10), tram(11), roadSideUnit(15)", + "type": "integer", + "default": 0, + "minimum": 0, + "maximum": 255 + } + } + }, + "situation_container": { + "type": "object", + "required": [ + "information_quality", + "event_type" + ], + "properties": { + "information_quality": { + "type": "integer", + "description": "The quality level of the information provided by the ITS-S application of the originating ITS-S. It indicates the probability of the detected event being truly existent at the event position.", + "$ref": "#/$defs/information_quality" + }, + "event_type": { + "$comment": "Choice has been made not to use CauseCodeV2 object as defined in DENM TS CDD, because it would require a object definition for each cause just to hold the subcause code; Using the deprecated CauseCode instead", + "type": "object", + "required": [ + "cause" + ], + "properties": { + "cause": { + "type": "integer", + "description": "reserved (0),trafficCondition (1),accident (2),roadworks (3),adverseWeatherCondition-Adhesion (6),hazardousLocation-SurfaceCondition (9),hazardousLocation-ObstacleOnTheRoad (10),hazardousLocation-AnimalOnTheRoad (11),humanPresenceOnTheRoad (12),wrongWayDriving (14),rescueAndRecoveryWorkInProgress (15),adverseWeatherCondition-ExtremeWeatherCondition (17),adverseWeatherCondition-Visibility (18),adverseWeatherCondition-Precipitation (19),slowVehicle (26),dangerousEndOfQueue (27),vehicleBreakdown (91),postCrash (92),humanProblem (93),stationaryVehicle (94),emergencyVehicleApproaching (95),hazardousLocation-DangerousCurve (96),collisionRisk (97),signalViolation (98),dangerousSituation (99)", + "minimum": 0, + "maximum": 255 + }, + "subcause": { + "type": "integer", + "description": "trafficCondition: unavailable(0), increasedVolumeOfTraffic(1), trafficJamSlowlyIncreasing(2), trafficJamIncreasing(3), trafficJamStronglyIncreasing(4), trafficStationary(5), trafficJamSlightlyDecreasing(6), trafficJamDecreasing(7), trafficJamStronglyDecreasing(8). accident: unavailable(0), multiVehicleAccident(1), heavyAccident(2), accidentInvolvingLorry(3), accidentInvolvingBus(4), accidentInvolvingHazardousMaterials(5), accidentOnOppositeLane(6), unsecuredAccident(7), assistanceRequested(8). roadworks: unavailable(0), majorRoadworks(1), roadMarkingWork(2), slowMovingRoadMaintenance(3), shortTermStationaryRoadworks(4), streetCleaning(5), winterService(6). humanPresenceOnTheRoad: unavailable(0), childrenOnRoadway(1), cyclistOnRoadway(2), motorcyclistOnRoadway(3). wrongWayDriving: unavailable(0), wrongLane(1), wrongDirection(2). adverseWeatherCondition-ExtremeWeatherCondition: unavailable(0), strongWinds(1), damagingHail(2), hurricane(3), thunderstorm(4), tornado(5), blizzard(6). adverseWeatherCondition-Adhesion: unavailable(0), heavyFrostOnRoad(1), fuelOnRoad(2), mudOnRoad(3), snowOnRoad(4), iceOnRoad(5), blackIceOnRoad(6), oilOnRoad(7), looseChippings(8), instantBlackIce(9), roadsSalted(10). adverseWeatherCondition-Visibility: unavailable(0), fog(1), smoke(2), heavySnowfall(3), heavyRain(4), heavyHail(5), lowSunGlare(6), sandstorms(7), swarmsOfInsects(8). adverseWeatherCondition-Precipitation: unavailable(0), heavyRain(1), heavySnowfall(2), softHail(3). slowVehicle: unavailable(0), maintenanceVehicle(1), vehiclesSlowingToLookAtAccident(2), abnormalLoad(3), abnormalWideLoad(4), convoy(5), snowplough(6), deicing(7), saltingVehicles(8). stationaryVehicle: unavailable(0), humanProblem(1), vehicleBreakdown(2), postCrash(3), publicTransportStop(4), carryingDangerousGoods(5). humanProblem: unavailable(0), glycemiaProblem(1), heartProblem(2). emergencyVehicleApproaching: unavailable(0), emergencyVehicleApproaching(1), prioritizedVehicleApproaching(2). hazardousLocation-DangerousCurve: unavailable(0), dangerousLeftTurnCurve(1), dangerousRightTurnCurve(2), multipleCurvesStartingWithUnknownTurningDirection(3), multipleCurvesStartingWithLeftTurn(4), multipleCurvesStartingWithRightTurn(5). hazardousLocation-SurfaceCondition: unavailable(0), rockfalls(1), earthquakeDamage(2), sewerCollapse(3), subsidence(4), snowDrifts(5), stormDamage(6), burstPipe(7), volcanoEruption(8), fallingIce(9). hazardousLocation-ObstacleOnTheRoad: unavailable(0), shedLoad(1), partsOfVehicles(2), partsOfTyres(3), bigObjects(4), fallenTrees(5), hubCaps(6), waitingVehicles(7). HazardousLocation-AnimalOnTheRoad: unavailable(0), wildAnimals(1), herdOfAnimals(2), smallAnimals(3), largeAnimals(4). CollisionRisk: unavailable(0), longitudinalCollisionRisk(1), crossingCollisionRisk(2), lateralCollisionRisk(3), vulnerableRoadUser(4). SignalViolation: unavailable(0), stopSignViolation(1), trafficLightViolation(2), turningRegulationViolation(3). RescueAndRecoveryWorkInProgress: unavailable(0), emergencyVehicles(1), rescueHelicopterLanding(2), policeActivityOngoing(3), medicalEmergencyOngoing(4), childAbductionInProgress(5). DangerousEndOfQueue: unavailable(0), suddenEndOfQueue(1), queueOverHill(2), queueAroundBend(3), queueInTunnel(4). DangerousSituation: unavailable(0), emergencyElectronicBrakeEngaged(1), preCrashSystemEngaged(2), espEngaged(3), absEngaged(4), aebEngaged(5), brakeWarningEngaged(6), collisionRiskWarningEngaged(7). VehicleBreakdown: unavailable(0), lackOfFuel (1), lackOfBatteryPower (2), engineProblem(3), transmissionProblem(4), engineCoolingProblem(5), brakingSystemProblem(6), steeringProblem(7), tyrePuncture(8). PostCrash: unavailable(0), accidentWithoutECallTriggered (1), accidentWithECallManuallyTriggered (2), accidentWithECallAutomaticallyTriggered (3), accidentWithECallTriggeredWithoutAccessToCellularNetwork(4)", + "default": 0, + "minimum": 0, + "maximum": 255 + } + } + }, + "linked_cause": { + "$comment": "Choice has been made not to use CauseCodeV2 object as defined in DENM TS CDD, because it would require a object definition for each cause just to hold the subcause code; Using the deprecated CauseCode instead", + "type": "object", + "required": [ + "cause" + ], + "properties": { + "cause": { + "type": "integer", + "description": "see the event type cause description", + "minimum": 0, + "maximum": 255 + }, + "subcause": { + "type": "integer", + "description": "see the event type subcause description", + "default": 0, + "minimum": 0, + "maximum": 255 + } + } + }, + "event_zone": { + "type": "array", + "description": "List of relative position, using the position indicated in the component eventPosition of the Management container as the reference position for the first position", + "items" : { + "type": "object", + "required": [ + "event_position", + "information_quality" + ], + "properties": { + "event_position": { + "$ref": "#/$defs/delta_reference_position" + }, + "event_delta_time": { + "type": "integer", + "description": "The recorded or estimated travel time between a position and a predefined reference position.", + "minimum": 0, + "maximum": 65535, + "$comment": "Unit: 10 millisecond" + }, + "information_quality": { + "description": "Information quality of the detection for this event point", + "$ref": "#/$defs/information_quality" + } + } + } + }, + "linked_denms": { + "type": "array", + "description": "List of action id pointing to DENMs that are semantically connected because applying to consecutive event zones at the same time", + "item": { + "type": "object", + "required": [ + "station_id", + "sequence_number" + ], + "properties": { + "station_id": { + "type": "integer", + "minimum": 0, + "maximum": 4294967295 + }, + "sequence_number":{ + "type": "integer", + "minimum": 0, + "maximum": 65535 + } + } + }, + "minimum": 1, + "maximum": 8 + }, + "event_end": { + "type": "integer", + "minimum": -8190, + "maximum": 8191, + "$comment": "Unit: meter; outOfRange(8190), unavailable(8191)" + } + } + }, + "location_container": { + "type": "object", + "required": [ + "traces" + ], + "properties": { + "event_speed": { + "type": "object", + "required": [ + "speed_value", + "speed_confidence" + ], + "properties": { + "speed_value": { + "description": "Speed value, i.e. the magnitude of the velocity-vector.", + "minimum": 0, + "maximum": 16383, + "$comment": "Unit 0.01 m/s. standstill(0), oneCentimeterPerSec(1), unavailable(16383), outOfRange(16832)" + }, + "speed_confidence": { + "type": "integer", + "description": "the confidence value of the speed value.", + "minimum": 1, + "maximum": 127, + "$comment": "Unit: 0.01 m/s. equalOrWithinOneCentimeterPerSec(1), equalOrWithinOneMeterPerSec(100), outOfRange(126), unavailable(127)" + } + } + }, + "event_position_heading": { + "type": "object", + "required": [ + "value", + "confidence" + ], + "properties": { + "value": { + "type": "integer", + "description": "The angle value, which can be estimated as the mean of the current distribution.", + "minimum": 0, + "maximum": 3601, + "$comment": "Unit: 0.1 degree. wgs84North(0), wgs84East(900), wgs84South(1800), wgs84West(2700), doNotUse(3600), unavailable(3601)" + }, + "confidence": { + "type": "integer", + "description": "The angle confidence value which represents the estimated accuracy of an angle value with a default confidence level of 95 %.", + "minimum": 1, + "maximum": 127, + "$comment": "Unit: 0.1 degree. equalOrWithinZeroPointOneDegree (1), equalOrWithinOneDegree (10), outOfRange(126), unavailable(127)" + } + } + }, + "detection_zones_to_event_position": { + "type": "array", + "description": "The detection zone information approaching the event position", + "minItems": 1, + "maxItems": 7, + "items": { + "type": "object", + "required": [ + "path" + ], + "properties": { + "path": { + "type": "array", + "description": "the path history, a path with a set of path points", + "maxItems": 40, + "items": { + "type": "object", + "required": [ + "path_position" + ], + "properties": { + "path_position": { + "$ref": "#/$defs/delta_reference_position", + "description": "offset position of a detected event point with regards to the previous detected event point (event_position)." + }, + "path_delta_time": { + "type": "integer", + "description": "time travelled by the detecting ITS-S since the previous detected event point (reference_time). tenMilliSecondsInPast(1)", + "minimum": 1, + "maximum": 65535 + } + } + } + } + } + } + }, + "road_type": { + "type": "integer", + "description": "Type of a road segment. urban-NoStructuralSeparationToOppositeLanes(0), urban-WithStructuralSeparationToOppositeLanes(1), nonUrban-NoStructuralSeparationToOppositeLanes(2), nonUrban-WithStructuralSeparationToOppositeLanes(3)", + "minimum": 0, + "maximum": 3 + } + } + }, + "alacarte_container": { + "type": "object", + "properties": { + "lane_position": { + "type": "integer", + "description": "A transversal position on the carriageway at a specific longitudinal position, in resolution of lanes of the carriageway.", + "minimum": -1, + "maximum": 14, + "$comment": "offTheRoad(-1), innerHardShoulder(0), innermostDrivingLane(1), secondLaneFromInside(2), outterHardShoulder(14)" + }, + "positioning_solution": { + "type": "integer", + "description": "The positioning technology being used to estimate a geographical position.", + "minimum": 0, + "maximum": 6, + "$comment": "noPositioningSolution(0), sGNSS(1), dGNSS(2), sGNSSplusDR(3), dGNSSplusDR(4), dR(5), manuallyByOperator(6)" + } + } + } + } + } + }, + "$defs": { + "information_quality": { + "type": "integer", + "default": 0, + "minimum": 0, + "maximum": 7, + "$comment": "unavailable(0), lowest(1), highest(7)" + }, + "delta_reference_position": { + "type": "object", + "required": [ + "delta_latitude", + "delta_longitude", + "delta_altitude" + ], + "properties": { + "delta_latitude": { + "type": "integer", + "description": "Offset latitude with regards to a defined latitude value. It may be used to describe a geographical point with regards to a specific reference geographical position.", + "default": 131072, + "minimum": -131071, + "maximum": 131072, + "$comment": "Unit: 0.1 micro degree (10^-7 degree)" + }, + "delta_longitude": { + "type:": "integer", + "description": " offset longitude with regards to a defined longitude value. It may be used to describe a geographical point with regards to a specific reference geographical position.", + "default": 131072, + "minimum": -131071, + "maximum": 131072, + "$comment": "Unit: 0.1 micro degree (10^-7 degree)" + }, + "delta_altitude": { + "type": "integer", + "description": "an offset altitude with regards to a defined altitude value. It may be used to describe a geographical point with regards to a specific reference geographical position.", + "default": 12800, + "minimum": -12700, + "maximum": 12800, + "$comment": "Unit: centimeter; negativeOutOfRange(-12700), positiveOutOfRange(12799), unavailable(12800)" + } + } + } + } +}