V2 inheritance features

imjadn-v1.0-cn03.md

@@ -2252,6 +2252,52 @@ RecordType = Record {2..*} // requires field_1 and either or both field_2 and fi
   3 field_3   String optional  
 ```
 
+#### 3.1.4.5 Inheritance
+
+> NOTE 1: Inheritance capabilities are a new feature in JADN v2.0.
+
+> NOTE 2: The JADN v2 inheritance-oriented `extends` type option is unrelated to
+> deprecated `extend` type option in JADN v1.
+
+JADN supports inheritance in information modeling, providing for class /
+subclass relationships. There are four type options to manage the class
+relationships among types.
+
+- `abstract`: The `abstract` option indicates that a type definition is only a
+  basis for defining sub-classes and should never be instantiated in data. 
+
+- `extends`: The `extends` option indicates that the associated type definition
+  is adding to the super-type on which it is based. An extending sub-type can
+  add new fields to its supertype but cannot redefine existing, inherited
+  fields.
+
+> *QUESTION:  Can a sub-type that extends specify that optional fields in the
+> supertype are requires in the subtype?*
+
+- `restricts`: The `restricts` option indicates that the associated type
+  definition is subtracting from the super-type on which it is based. A
+  restricting sub-type can remove optional fields defined in its supertype,
+  however required fields cannot be removed.
+
+- `final`: The `final` type option identifies a type that cannot have sub-types
+  defined based on it.
+
+Inheritance can be applied both to primitive and compound types, although only
+the `restricts` type option is applicable to primitive types. For example,
+consider the following set of types:
+
+```
+A = String{1..32} abstract
+B = String restricts(A) /email
+C = String restricts(A) /hostname
+```
+
+Type "A" defines a String of between 1 and 32 characters, but because it is
+`abstract` no actual string data can be validated as conforming to type "A".
+However an email address shorter than 33 characters can be validated against
+type "B"; similarly a hostname shorter than 33 characters can be validated
+against type "C".
+
 ### 3.1.5 Reference Relationships: Keys and Links
 
 As explained in [Section 3](#3-creating-information-models-with-jadn), JADN recognizes
@@ -3300,7 +3346,7 @@ The following individuals have participated in the creation of this document and
 | imjadn-v1.0-cn03.md      | 2023-11-26 | David Lemire | Add example development JADN IM from JSON schema starting point (PR #xx), rename document for next CN version |
 | imjadn-v1.0-cn03.md      | 2023-12-11 | David Lemire | Add "Why JADN?" material in Section 1.1 (PR #88) |
 | imjadn-v1.0-cn03.md      | 2023-12-xx | David Lemire | Consolidate duplicative 2.1 content into 1.1.3 (PR #89) |
-
+| imjadn-v1.0-cn03.md      | 2025-01-xx | David Lemire | New content addressing inheritance features added in JADV v2 (PR #92) |
 -------
 
 # Appendix D. Frequently Asked Questions (FAQ)

schemas/geo-inheritance.jadn

@@ -0,0 +1,107 @@
+{
+  "types": [
+    ["Coordinate", "Array", [], "A single geographic point (latitude / longitude)", [
+        [1, "latitude", "Number", ["y-90", "z90"], ""],
+        [2, "longitude", "Number", ["y-180", "z180"], ""]
+      ]],
+    ["Coordinates", "ArrayOf", ["*Coordinate"], "A list of geographic points"],
+    ["PolUnit", "String", [], "the name of the political area where the feature exists (city / county / state level, as appropriate)"],
+    ["Endpoint", "Record", [], "", [
+        [1, "endpoint", "Coordinate", [], "center of start or end point of a linear feature, in lat/long"],
+        [2, "politicalUnit", "PolUnit", [], "the name of the political area where the endpoint exists"]
+      ]],
+    ["Endpoints", "ArrayOf", ["*Endpoint", "{2", "}2", "q"], "center of start/end points of a linear feature, in lat/long"],
+    ["Location", "Record", [], "", [
+        [1, "geoCenter", "Coordinate", [], "geographic center of the feature of interest at the location"],
+        [2, "politicalUnit", "PolUnit", [], "the name of the political area where the location exists"]
+      ]],
+    ["OpenSpace", "Record", [], "extends(Location) -- a defined area of open space", [
+        [1, "edges", "Coordinates", [], "an array of lat/long points defining the line segments around the perimeter of a feature, equivalent to the gml:LinearRing; the first and last Coordinates in the array MUST match"]
+      ]],
+    ["Road", "Record", [], "extends(Location) abstract -- essential information about any road", [
+        [1, "endpoints", "Endpoints", [], "center of start/end points of a road, in lat/long + political unit"],
+        [2, "waypoints", "Coordinates", [], ""],
+        [3, "width", "Number", ["y1"], "Width of the road in meters. MUST be >0"],
+        [4, "name", "String", [], "official (or commonly used) name of the road"],
+        [5, "maintainedBy", "Maintainer", [], "what level of government is responsible for maintenance"]
+      ]],
+    ["LocalRoad", "Record", [], "extends(Road)", [
+        [1, "surfaceType", "Surface", [], "Choice identifying the type of road surface"]
+      ]],
+    ["NumberedRoad", "Record", [], "extends(Road)", [
+        [1, "routeNumber", "RouteNumber", [], "State or U.S. identifying number of the road"]
+      ]],
+    ["Interstate", "Record", [], "extends(Road)", [
+        [1, "interstateNumber", "Integer", ["{1", "}999"], "Interstate number of the road"]
+      ]],
+    ["RouteNumber", "Array", [], "", [
+        [1, "owningEntity", "String", ["%[A-Z]{2}"], "\"US\" or 2-character State portion of road number"],
+        [2, "routeNum", "Integer", ["{1", "}1000"], "numeric portion of road identifier"]
+      ]],
+    ["Surface", "Choice", [], "(oneOf) possible road surfaces", [
+        [1, "dirt", "String", [], ""],
+        [2, "gravel", "String", [], ""],
+        [3, "macadam", "String", [], ""],
+        [4, "concrete", "String", [], ""],
+        [5, "asphalt", "String", [], ""]
+      ]],
+    ["Maintainer", "Enumerated", [], "level of government responsible for maintaining a road", [
+        [1, "local", "town or city"],
+        [2, "county", ""],
+        [3, "state", ""],
+        [4, "federal", ""]
+      ]],
+    ["BridgePurpose", "Enumerated", [], "", [
+        [1, "vehicular", ""],
+        [2, "pedestrian", ""],
+        [3, "railroad", ""]
+      ]],
+    ["Construction", "Record", [], "extends(Location) abstract -- no unique fields", []],
+    ["Bridge", "Record", [], "extends(Construction)", [
+        [1, "endpoints", "Endpoints", [], ""],
+        [2, "waypoints", "Coordinates", [], ""],
+        [3, "width", "Number", [], ""],
+        [4, "maxHeight", "Number", [], ""],
+        [5, "name", "String", [], ""],
+        [6, "purpose", "BridgePurpose", ["[1"], ""]
+      ]],
+    ["Tunnel", "Record", [], "extends(Construction)", [
+        [1, "endpoints", "Endpoints", [], ""],
+        [2, "waypoints", "Coordinates", [], ""],
+        [3, "width", "Number", [], ""],
+        [4, "height", "Number", [], ""],
+        [5, "depth", "Number", [], ""],
+        [6, "name", "String", [], ""],
+        [7, "purpose", "TunnelPurpose", ["[1"], ""]
+      ]],
+    ["Building", "Record", [], "extends(Construction)", [
+        [1, "address", "Address", [], ""],
+        [2, "edges", "Coordinates", [], "an array of lat/long points defining the line segments around the perimeter of a feature, equivalent to the gml:LinearRing; the first and last Coordinates in the array MUST match"],
+        [3, "maxHeight", "Number", [], "maximum height of the building in meters"],
+        [4, "function", "BuildingFunction", ["[1"], ""]
+      ]],
+    ["Address", "Map", [], "A street / postal address associated with a building", [
+        [1, "street", "String", [], ""],
+        [2, "apartment", "String", ["[0", "]1"], ""],
+        [3, "suite", "String", ["[0", "]1"], ""],
+        [4, "county", "String", ["[0", "]1"], ""],
+        [5, "city", "String", [], ""],
+        [6, "state", "String", ["%[A-Z]{2}"], ""],
+        [7, "zipCode", "String", ["%\\d{5}(\\-\\d{4}){0,1}"], "zip+4 format implies a U.S. postal code"]
+      ]],
+    ["TunnelPurpose", "Enumerated", [], "", [
+        [1, "vehicular", ""],
+        [2, "pedestrian", ""],
+        [3, "railroad", ""],
+        [4, "water", ""]
+      ]],
+    ["BuildingFunction", "Enumerated", [], "", [
+        [1, "Single-Family Dwelling", ""],
+        [2, "Multi-Family Dwelling", ""],
+        [3, "Commercial-Office", ""],
+        [4, "Commercial-Retail", ""],
+        [5, "Medical", ""],
+        [6, "Government", ""]
+      ]]
+  ]
+}

schemas/geo-inheritance.jidl

@@ -0,0 +1,118 @@
+Coordinate = Array
+  1 Number {-90., 90.}      // latitude::
+  2 Number {-180., 180.}    // longitude::
+
+PolUnit = String    // the name of the political area where the feature exists 
+                    // (city / county / state level, as appropriate);
+
+Location = Record abstract
+    1 geoCenter         Coordinate          // geographic center of the feature of interest at the location
+    2 politicalUnit     PolUnit optional    // the name of the political area where the location exists 
+
+EndPoint = Record restricts(Location)
+    1 endpoint          Coordinate          // center of start or end point of a linear feature, in lat/long
+    2 politicalUnit     PolUnit required    // the name of the political area where the endpoint exists 
+
+EndPoints = ArrayOf(EndPoint){2..2}     // center of start/end points of a linear feature, in lat/long
+
+Coordinates = ArrayOf(Coordinate)
+
+OpenSpace = Record extends(Location)
+    3 boundary  Coordinates // an array of lat/long points defining the line segments around 
+                            // the perimeter of a feature, equivalent to the gml:LinearRing
+                            // USAGE: the first and last Coordinates in the array MUST match
+
+Road = Record extends(Location) abstract
+    3 endPoints     Endpoints       // center of start/end points of a road, in lat/long + political unit
+    4 wayPoints     Coordinates     // list of center points (lat/long) of a road that defines 
+                                    // its route; curvature is approximated as straight line segments 
+                                    // between waypoints, enabling arbitrary precision about the route
+    5 width         Number (0., ]   // width of the road in meters, MUST be >0
+    6 name          String          // official (or commonly used) name of the road
+    7 maintainedBy  Maintainer      // what level of government is responsible for maintenance
+
+LocalRoad = Record extends(Road)
+    8 surfaceType   Surface         // Choice identifying the type of road surface 
+                                    // (e.g., asphalt, concrete, gravel, dirt)
+
+NumberedRoad = Record extends(Road)
+    8 routeNumber   RouteNumber     // State or U.S. identifying number of the road, if applicable
+
+Interstate = Record extends(Road)
+    8 interstateNumber   Integer [1, 999]   // Interstate number of the road
+
+RouteNumber = Array
+    1 String                //owningEntity:: "US" or 2-character State portion of road number
+    2 Integer [1, 1000]     //routeNum:: numeric portion of road identifier
+
+Maintainer = Enumerated // level of government responsible for maintaining a road
+    1   local   // city or town
+    2   county
+    3   state
+    4   federal
+
+Surface = Choice (oneOf)
+    1 dirt
+    2 gravel
+    3 macadam
+    4 asphalt
+    5 concrete
+
+Construction = Record extends(Location) abstract
+
+Building = Record extends(Construction)
+    3 address   Address
+    4 perimeter Coordinates // an array of lat/long points defining the line segments around 
+                            // the perimeter of a feature, equivalent to the gml:LinearRing
+                            // USAGE: the first and last Coordinates in the array MUST match
+    5 maxHeight Number      // maximum height of the building in meters
+    6 function  BuildingFunction{1..*}
+
+Tunnel = Record extends(Construction)
+    3 endPoints     Endpoints       // center of start and end points of a tunnel, in lat/long plus political unit
+    4 wayPoints     Coordinates     // list of center points (lat/long) of a tunnel that defines 
+                                    // its route; curvature is approximated as straight line segments 
+                                    // between waypoints, enabling arbitrary precision about the route
+    5 width         Number (0., -1.]    // width of the tunnel in meters, MUST be >0
+    6 height        Number          // height of a tunnel from road surface to ceiling, in meters
+    7 depth         Number          // lowest elevation of a tunnel's road surface, in meters
+    8 name          String          // official (or commonly used) name of the tunnel
+    9 purpose       TunnelPurpose{1..*} // purpose of this tunnel
+
+Bridge = Record extends(Construction)
+    3 endPoints     Endpoints       // center of start and end points of a bridge, in lat/long
+    4 wayPoints     Coordinates     // list of center points (lat/long) of a bridge that defines 
+                                    // its route; curvature is approximated as straight line segments 
+                                    // between waypoints, enabling arbitrary precision about the route
+    5 width         Number (0., -1.]    // width of the bridge in meters, MUST be >0
+    6 maxHeight     Number              // maximum height of the bridge in meters
+    7 name          String          // official (or commonly used) name of the bridge
+    8 purpose       BridgePurpose{1..*} // purpose of this Bridge
+
+BuildingFunction = Enumerated
+    1 Single-Family Dwelling
+    2 Multi-Family Dwelling
+    3 Commercial-Office
+    4 Commercial-Retail
+    5 Medical
+    6 Government
+
+TunnelPurpose = Enumerated
+    1 vehicular
+    2 pedestrian
+    3 railroad
+    4 water
+
+BridgePurpose = Enumerated
+    1 vehicular
+    2 pedestrian
+    3 railroad
+
+Address = Map
+    1 street    String
+    2 apartment String optional
+    3 suite     String optional
+    4 county    String optional
+    5 city      String
+    6 state     String{pattern="[A-Z]{2}"}
+    7 postCode  String{pattern="/\d{5}(\-\d{4}){0,1}"}