api: railjson V3

[Tguisnet]

close #1909

Changelog in railjson v3

In a nutshell :

Appart from the errors, ObjectRef dissappeared from all objects to become a String.
(or a Waypoint for route entry/exit point)
Cosmetic fields are put in a struct for their scope (SncfExtension, or IdentifierExtension for example).
Those structs are put in an other struct containing all different scope of extension (TrackSectionExtension, or OperationalPointExtension for example) and they are optional.

Tracksection :

• navigability : suppressed
• extensions : new field containing TrackSectionExtensions struct
• TrackSectionExtensions : new struct containing optional TrackSectionSncfExtension struct
• fields line_code, line_name, track_number, track_name are moved in TrackSectionSncfExtension

Detector :

• track : type changed from ObjectRef to String (of the track's id)

BufferStop :

• track : type changed from ObjectRef to String (of the track's id)

Waypoint (new) :

• this is a polymorphic reference on BufferStop or Detector, This is used for the entry and exit point of the routes.

ApplicableDirectionsTrackRange :

• track : type changed from ObjectRef to String (of the track's id)

DirectionalTrackRange :

• track : type changed from ObjectRef to String (of the track's id)

TrackEndpoint :

• track : type changed from ObjectRef to String (of the track's id)

OperationalPoint :

• extensions : new field containing OperationalPointExtensions structure
• OperationalPointExtensions : new struct containing OperationalPointSncfExtension and OperationalPointIdentifierExtension structures both optional
• fields name and uic are moved in OperationalPointIdentifierExtension
• fields ch_short_label, ch_long_label, ci, ch, trigram are moved in OperationalPointSncfExtension
• OperationalPointPart : track type changed from ObjectRef to String (of the track's id)

Route :

entry_point : type changed from ObjectRef to Waypoint
exit_point : type changed from ObjectRef to Waypoint
release_detectors : type change from List<ObjectRef> to List<String>

Signal :

• track : type changed from ObjectRef to String (of the track's id)
• linked_detector : type changed from Optional<ObjectRef> an optional Optional<String>
• extensions : new field containing SignalExtensions struct
• SignalExtensions : new struct containing optional SignalSncfExtension
• fields default_aspect, installation_type, is_in_service, is_lightable, is_operational, label, physical_organization_group, responsible_group, side, support_type, type_code, value are moved in SignalSncfExtension

Switch :

• switch_type : type changed from ObjectRef to String

SwitchType :

• bidirectional : suppressed

TrackSectionLink :

• navigabilty : suppressed

[multun]

is it what you had in mind?

{
    "id": "track.42",
    "extensions": {
        "sncf": {"foo": "bar"}
    }
}

If so, metaprogramming feels overkill

[flomonster]

It's exactly what we want to achieve here. Metaprog kind of simplified a lot the code.

[flomonster]

• Remove applicable_train_type (not used in core)
• API could adapt its endpoint to download railjson without extensions
• Rework refs. Could be less flexible.
• Rework signals cosmetic fields
• Remove bidirectional from the SwitchPortConnection
  • The navigability is manged only with routes (needed to be documented)

[flomonster]

New route schema suggestion:

class Route(BaseObjectTrait):
    """
    This class is used to describe routes on the infrastructure.
    """

    entry_point: ObjectReference = Field(description="Identifier and type used to define an entry point for the route")
    entry_point_direction: ObjectReference = Field(description="Identifier and type used to define an entry point for the route")
    exit_point: ObjectReference = Field(description="Identifier and type used to define an exit point for the route")
    release_detectors: List[ObjectReference] = Field(
        description="Detector allowing the release of resources reserved from the beginning of the route until this one"
    )
    switches_directions: List[Tuple[ObjectReference, str]] = ...

[codecov]

Codecov Report

Merging #1933 (9827427) into dev (7e0711c) will increase coverage by 0.02%.
The diff coverage is 84.56%.

❗ Current head 9827427 differs from pull request most recent head 7f1a6a3. Consider uploading reports for the commit 7f1a6a3 to get more accurate results

@@             Coverage Diff              @@
##                dev    #1933      +/-   ##
============================================
+ Coverage     80.12%   80.15%   +0.02%     
+ Complexity     1636     1631       -5     
============================================
  Files           261      261              
  Lines          8448     8354      -94     
  Branches        939      941       +2     
============================================
- Hits           6769     6696      -73     
+ Misses         1284     1261      -23     
- Partials        395      397       +2     

Flag	Coverage Δ
core	80.79% <90.00%> (-0.05%)	⬇️
editoast	78.65% <83.62%> (+0.15%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
...a/fr/sncf/osrd/railjson/schema/infra/RJSRoute.java	50.00% <ø> (ø)
.../fr/sncf/osrd/railjson/schema/infra/RJSSwitch.java	0.00% <ø> (ø)
...sncf/osrd/railjson/schema/infra/RJSSwitchType.java	93.33% <ø> (+5.09%)	⬆️
...cf/osrd/railjson/schema/infra/RJSTrackSection.java	100.00% <ø> (+28.57%)	⬆️
...srd/railjson/schema/infra/RJSTrackSectionLink.java	83.33% <ø> (-2.39%)	⬇️
...ljson/schema/infra/trackobjects/RJSBufferStop.java	100.00% <ø> (ø)
.../railjson/schema/infra/trackobjects/RJSSignal.java	85.71% <ø> (ø)
...json/schema/infra/trackobjects/RJSTrackObject.java	100.00% <ø> (ø)
...on/schema/infra/trackobjects/RJSTrainDetector.java	100.00% <ø> (ø)
...trackranges/RJSApplicableDirectionsTrackRange.java	85.71% <ø> (ø)
... and 51 more

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.