From: JvD_Ericsson Date: Fri, 7 Jun 2024 12:53:56 +0000 (+0100) Subject: Add developer docs X-Git-Tag: 0.0.1~3^2 X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=d18250375ad47203908900f1109444d1d21006a6;p=smo%2Fteiv.git Add developer docs Comments addressed by 12955: Update developer docs | https://gerrit.o-ran-sc.org/r/c/smo/teiv/+/12955 Issue-ID: SMO-150 Change-Id: Id13c3485f0c074226e2bf2172cc30aec30b03f02 Signed-off-by: JvD_Ericsson --- diff --git a/.gitignore b/.gitignore index 713206a..3569c70 100644 --- a/.gitignore +++ b/.gitignore @@ -31,3 +31,6 @@ yang-parser/src/test/resources/_orig-modules/_3gpp*.yang yang-parser/src/test/resources/_orig-modules/iana*.yang pgsql-schema-generator/src/test/resources/generate-defaults/import/*.yang teiv/src/main/resources/models/import/*.yang + +.tox +docs/_build \ No newline at end of file diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..10a0cdb --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,35 @@ +# ============LICENSE_START======================================================= +# Copyright (C) 2024 Ericsson +# Modifications Copyright (C) 2024 OpenInfra Foundation Europe +# ================================================================================ +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 +# ============LICENSE_END========================================================= +--- +version: 2 + +formats: + - htmlzip + +build: + os: ubuntu-22.04 + tools: + python: "3.11" + +python: + install: + - requirements: docs/requirements-docs.txt + +sphinx: + configuration: docs/conf.py diff --git a/docs/_static/data-model/equipment-ran.svg b/docs/_static/data-model/equipment-ran.svg new file mode 100644 index 0000000..066132a --- /dev/null +++ b/docs/_static/data-model/equipment-ran.svg @@ -0,0 +1 @@ +Equipment-RAN Object RelationshipsAntennaCapabilitySERVESSectorAntennaModuleGROUPSRANEquipment \ No newline at end of file diff --git a/docs/_static/data-model/equipment-relationships.svg b/docs/_static/data-model/equipment-relationships.svg new file mode 100644 index 0000000..b87aee0 --- /dev/null +++ b/docs/_static/data-model/equipment-relationships.svg @@ -0,0 +1 @@ +Equipment Object RelationshipsAntennaModuleSiteINSTALLED_AT \ No newline at end of file diff --git a/docs/_static/data-model/equipment.svg b/docs/_static/data-model/equipment.svg new file mode 100644 index 0000000..7e66d1a --- /dev/null +++ b/docs/_static/data-model/equipment.svg @@ -0,0 +1 @@ +Equipment Managed Objects and Attributeso-ran-smo-teiv-equipmentAntennaModuleSitestring {key}id:stringantennaModelNumber: uint32mechanicalAntennaBearing: uint32mechanicalAntennaTilt: stringpositionWithinSector: uint32totalTilt: uint32electricalAntennaTilt: uint32antennaBeamWidth:string {key}id:Stringname:decimal64v-north:decimal64v-east:decimal64v-up:locationchoice:decimal64latitude:decimal64longitude:decimal64height:decimal64x:decimal64y:decimal64z:stringalternate-system:stringastronomical-body:stringgeodetic-datum:decimal64coord-accuracy:decimal64height-accuracy:timestamp yang:date-and-timevalid-until: yang:date-and-timegeo-location:decimal64v-north:decimal64v-east:decimal64v-up:locationchoice:decimal64latitude:decimal64longitude:decimal64height:decimal64x:decimal64y:decimal64z:stringalternate-system:stringastronomical-body:stringgeodetic-datum:decimal64coord-accuracy:decimal64height-accuracy:timestamp yang:date-and-timevalid-until: yang:date-and-timegeo-location: \ No newline at end of file diff --git a/docs/_static/data-model/oam-ran.svg b/docs/_static/data-model/oam-ran.svg new file mode 100644 index 0000000..0ee7127 --- /dev/null +++ b/docs/_static/data-model/oam-ran.svg @@ -0,0 +1 @@ +OAM-RAN Object RelationshipsManagedElementMANAGESENodeBFunctionGNBDUFunctionMANAGESGNBCUCPFunctionMANAGESMANAGESGNBCUUPFunctionOAMRAN \ No newline at end of file diff --git a/docs/_static/data-model/oam.svg b/docs/_static/data-model/oam.svg new file mode 100644 index 0000000..d072b8b --- /dev/null +++ b/docs/_static/data-model/oam.svg @@ -0,0 +1 @@ +OAM Managed Objects and Attributeso-ran-smo-teiv-oamManagedElementstring {key}id: \ No newline at end of file diff --git a/docs/_static/data-model/ran-relationships.svg b/docs/_static/data-model/ran-relationships.svg new file mode 100644 index 0000000..cf4f396 --- /dev/null +++ b/docs/_static/data-model/ran-relationships.svg @@ -0,0 +1 @@ +RAN Object RelationshipsGNBDUFunctionNRCellCUNRCellDUENodeBFunctionEUtranCellNrSectorCarrierLTESectorCarrierAntennaCapabilityPROVIDESPROVIDESPROVIDESPROVIDESUSESUSESUSESUSESGNBCUCPFunctionPROVIDESSectorGROUPSGROUPS \ No newline at end of file diff --git a/docs/_static/data-model/ran.svg b/docs/_static/data-model/ran.svg new file mode 100644 index 0000000..3481cb2 --- /dev/null +++ b/docs/_static/data-model/ran.svg @@ -0,0 +1 @@ +RAN Managed Objects and Attributeso-ran-smo-teiv-ranGNBDUFunctionGNBCUUPFunctionNRCellCUNRCellDUENodeBFunctionGNBCUCPFunctionEUtranCellNrSectorCarrierLTESectorCarrierAntennaCapabilitystring {key}id:uint32gNBDUId: uint32gNBId: uint32gNBIdLength:string {key}id:stringgNBCUName: uint32gNBId: uint32gNBIdLength:string {key}id:uint32gNBId: uint32gNBIdLength:mcc: Mccmnc: MncdUpLMNId:mcc: Mccmnc: MncpLMNId:string {key}id:uint32cellLocalId: uint32nCI: uint32nRTAC:string {key}id:uint32cellLocalId: uint32nCI: uint32nRPCI:uint32nRTACstring {key}id:uint32eNBId: string {key}id:uint32cellId:uint32earfcndluint32earfcnuluint32dlChannelBandwidth: uint32Earfcnuint32channelBandwidth: uint32tac:enum: {fdd, tdd}duplexType:string {key}id:uint32arfcnDL:uint32arFcnUL:uint32frequencyDLuint32frequencyUL:uint32bSChannelBwDL:string {key}id:enum: {normal_sector, left_digital_sector, right_digital_sector,...}sectorCarrierTypestring {key}id:stringeUtranFqBands[]:stringgeranFqBands[]:stringnRFqBands[]:mcc: Mccmnc: MncpLMNId:mcc: int32 [0..999]mnc: int32 [0..999]mncLength: int32 [2..3]eNodeBPlmnId:Sectorstring {key}id:uint64sectorid:decimal64 {degrees}azimuth:timestamp yang:date-and-timevalid-until: yang:date-and-timegeo-location:stringalternate-system:stringastronomical-body:decimal64v-north:decimal64v-east:decimal64v-up:locationchoicedecimal64latitude:decimal64longitude:decimal64height:decimal64x:decimal64y:decimal64z:stringgeodetic-datum:decimal64coord-accuracy:decimal64 {meters}height-accuracy: \ No newline at end of file diff --git a/docs/_static/data-model/yang-types.svg b/docs/_static/data-model/yang-types.svg new file mode 100644 index 0000000..8e0e621 --- /dev/null +++ b/docs/_static/data-model/yang-types.svg @@ -0,0 +1 @@ +Common YANG Typeso-ran-smo-teiv-common-yang-typesdecoratorsclassifierssourceIdsmetadatatype: classifier[]type: string[] containerleaf-list \ No newline at end of file diff --git a/docs/_static/logo.png b/docs/_static/logo.png new file mode 100644 index 0000000..c3b6ce5 Binary files /dev/null and b/docs/_static/logo.png differ diff --git a/docs/_static/sample-entities.svg b/docs/_static/sample-entities.svg new file mode 100644 index 0000000..f6d4805 --- /dev/null +++ b/docs/_static/sample-entities.svg @@ -0,0 +1 @@ +Sample Entities with AttributesGNBCUUPFunctionNRCellCUstring {key}id:uint32gNBId: uint32gNBIdLength:string {key}id:uint32cellLocalId: uint32nCI: uint32nRTAC:mcc: Mccmnc: MncpLMNId: \ No newline at end of file diff --git a/docs/_static/sample-object-relationships.svg b/docs/_static/sample-object-relationships.svg new file mode 100644 index 0000000..9cab9f4 --- /dev/null +++ b/docs/_static/sample-object-relationships.svg @@ -0,0 +1 @@ +Sample Managed Objects and their RelationshipsGNBDUFunctionNRCellCUNRCellDUENodeBFunctionEUtranCellNrSectorCarrierLTESectorCarrierAntennaCapabilityPROVIDESPROVIDESPROVIDESPROVIDESUSESUSESUSESUSESGNBCUCPFunctionPROVIDESSectorGROUPSGROUPS \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..8846070 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,30 @@ +# ============LICENSE_START======================================================= +# Copyright (C) 2024 Ericsson +# Modifications Copyright (C) 2024 OpenInfra Foundation Europe +# ================================================================================ +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 +# ============LICENSE_END========================================================= + +from docs_conf.conf import * + +project = "teiv" +release = "master" +version = "master" + +author = "ORAN" + +extensions = [ + 'sphinx.ext.autosectionlabel', +] diff --git a/docs/conf.yaml b/docs/conf.yaml new file mode 100644 index 0000000..83d5e1f --- /dev/null +++ b/docs/conf.yaml @@ -0,0 +1,3 @@ +--- +project_cfg: oran +project: teiv diff --git a/docs/data-models-guide.rst b/docs/data-models-guide.rst new file mode 100644 index 0000000..a953244 --- /dev/null +++ b/docs/data-models-guide.rst @@ -0,0 +1,75 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2024 Nordix Foundation. All rights Reserved +.. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved + +Topology & Inventory Data Models +================================ + +The following are the currently supported modules in Topology & +Inventory. + +Common YANG extensions +---------------------- +.. literalinclude:: ../teiv/src/main/resources/models/o-ran-smo-teiv-common-yang-extensions.yang + :language: yang + +Common YANG types +----------------- + +.. image:: _static/data-model/yang-types.svg + :width: 900 + +.. literalinclude:: ../teiv/src/main/resources/models/o-ran-smo-teiv-common-yang-types.yang + :language: yang + +Equipment +--------- + +.. image:: _static/data-model/equipment.svg + :width: 900 + +.. image:: _static/data-model/equipment-relationships.svg + :width: 900 + +.. literalinclude:: ../teiv/src/main/resources/models/o-ran-smo-teiv-equipment.yang + :language: yang + +RAN +--- + +.. image:: _static/data-model/ran.svg + :width: 900 + +.. image:: _static/data-model/ran-relationships.svg + :width: 900 + +.. literalinclude:: ../teiv/src/main/resources/models/o-ran-smo-teiv-ran.yang + :language: yang + +Relationship: Equipment RAN +--------------------------- + +.. image:: _static/data-model/equipment-ran.svg + :width: 900 + +.. literalinclude:: ../teiv/src/main/resources/models/o-ran-smo-teiv-equipment-to-ran.yang + :language: yang + +OAM +--- + +.. image:: _static/data-model/oam.svg + :width: 900 + +.. literalinclude:: ../teiv/src/main/resources/models/o-ran-smo-teiv-oam.yang + :language: yang + +Relationship: OAM RAN +--------------------- + +.. image:: _static/data-model/oam-ran.svg + :width: 900 + +.. literalinclude:: ../teiv/src/main/resources/models/o-ran-smo-teiv-oam-to-ran.yang + :language: yang diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst new file mode 100644 index 0000000..c89590c --- /dev/null +++ b/docs/developer-guide.rst @@ -0,0 +1,245 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2024 Nordix Foundation. All rights Reserved +.. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved + +Developer Guide +############### + +Developer Guide Overview +======================== + +In this guide, we explore the use of Topology & Inventory to manage the +topology and inventory data in your network. + +Introducing topology and inventory data +======================================= + +Topology and inventory data is the information that represents entities +in a telecommunications network and the relationships between them that +provide insight into a particular aspect of the network of importance to +specific use cases. Topology and inventory data can be derived from +inventory, configuration, or other data. Topology & Inventory is being +updated autonomously based on changes in the network. + +Topology & Inventory supports several topology and inventory domains, +see the :doc:`Data Models ` for +details on the topology and inventory model. The understanding of the +model is important to enable a user making queries on topology and +inventory data. The entities are modeled as managed objects (found under +the schema in the data dictionary) and grouped together in modules based +on functionality. See +:ref:`Supported domains ` +for the list of the topology and inventory domains currently supported +in Topology & Inventory capability. + +Concepts +-------- + +The building blocks of the Topology & Inventory are domains, entities, +and the relationships between each other. From a graph perspective, +entities are the vertices and relationships are the edges. These two +components are part of a subgraph, or the so-called domain. A +relationship can go beyond a single domain, since it can happen that the +two entities come from two separate ones. In this particular case, they +have a cross-domain relationship. + +Domain +~~~~~~ + +A domain is a grouping of topology and inventory entities that handles +topology and inventory data. Topology and inventory data is the +information that represents entities in a telecommunications network and +the relationships between them that provides insight into a particular +aspect of the network of import to specific use cases. Topology and +inventory data can be derived from inventory, configuration, or other +data. Therefore, the topology and inventory model must define what the +telecoms network entities and relationships are. More information can be +found in :ref:`Supported domains `. +The Topology Exposure and Inventory Management (TEIV) domain is the +parent domain used for entities and relationships. This domain can be +used in reading and querying topology and inventory data when the domain +name of an entity or relationship is not known. + +Entity +~~~~~~ + +Entities are enabling the modelling and storage of complex network +infrastructure and relationships. The following are two examples of the +entities and their attributes from :doc:`Topology & Inventory Data +Models `. + +.. image:: _static/sample-entities.svg + :width: 900 + +Relationship +~~~~~~~~~~~~ + +It is a bi-directional connection between two entities, one of which is +the originating side (A-side) and the other is the terminating side +(B-side). The order of the sides matters since it defines the +relationship itself which must be unique. A relationship between two +entities is based on the effect that one has on the other. An entity can +have one or multiple relationships which can be defined by the user. A +possible relationship between ManagedElement and GNBDUFunction can be +*MANAGEDELEMENT_MANAGES_GNBDUFUNCTION*. + +Topology & Inventory models +--------------------------- + +The Topology & Inventory objects are managed and standardized using YANG +models. These YANG models describe managed network entities and their +attributes, while also providing information on the relations between +the network entities. YANG data models are structured into modules and +submodules. Management instance data is a graph of objects which have +attributes (see the **schema** in the data models). + +The :doc:`Topology & Inventory Data Models ` includes: +- Modules for each supported domain that describe the structure of the +managed objects within it as well as any relationships between them. - +Modules that describe cross-domain relationships. - Modules that define +proprietary extensions and types used to describe the structure of +objects and attributes within the domains. + +The following sample diagram shows some managed objects and their +relationships in the RAN domain. + +.. image:: _static/sample-object-relationships.svg + :width: 900 + +A direct relationship is a connection between two entities without any +in-between entity and an indirect relationship contains at least one. +NRCellDU has direct relationships with GNBDUFunction and +NRSectorCarrier, while it also has indirect relationships with +ManagedElement, AntennaCapability, and AntennaModule. + +Supported domains +----------------- + ++-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Domain | Description | ++===================+=============================================================================================================================================================================================================================================================================+ +| RAN | This model contains the topology entities and relations in the RAN domain, which represents the functional capability of the deployed RAN that are relevant to rApps use cases. | ++-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| EQUIPMENT | This model contains the topology entities and relations in the Equipment domain, which is modelled to understand the physical location of equipment such as antennas associated with a cell/carrier and their relevant properties, for example, tilt, max power, and so on. | ++-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| OAM | This model contains the topology entities and relations in the O&M domain, which are intended to represent management systems and management interfaces. | ++-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| REL_EQUIPMENT_RAN | This model contains the topology relations between Equipment and RAN. | ++-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| REL_OAM_RAN | This model contains the topology relations between O&M and RAN. | ++-------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + + +Retrieving and using topology modules +===================================== + +Topology & Inventory provides APIs to enable users :download:`query module +data <../teiv/src/main/resources/v1/topology-exposure-inventory-openapi.yaml>` +that can be used to understand the existing topology and inventory model, +parse the modules, and understand what objects are supported over the R1 +interface, so adequate queries can be made on topology and inventory data. + +The API endpoints returning lists support pagination. The default value +for number of items returned is 500, which is also the upper limit. + +**Sample request to fetch a list of all modules:** + +:: + + GET https:///topology-inventory//schemas + +To get a list of all modules for a specific domain, use a *domain* query +parameter. For example, /schemas?domain= + +**Sample request to fetch a list of all modules related to the RAN +domain:** + +:: + + GET https:///topology-inventory//schemas?domain=ran + +.. + + **Note:** - Partial matches are also supported in the query parameter + using the ’*’ symbol as a wild card. - If the specified domain does + not exist, an empty list is returned. + +To get a specific module, supply a module name in the path parameter. +For example, /schemas//content + +**Sample request to fetch the module data for the o-ran-smo-teiv-ran +module:** + +:: + + GET https:///topology-inventory//schemas/o-ran-smo-teiv-ran/content + +.. + + **Note:** If the specified module does not exist, an + *INVALID_MODULE_NAME* error is returned. + +Reading and querying topology and inventory +=========================================== + +Reading entities and relationships +---------------------------------- + +To get a list of all entities with all properties in a specified domain +name, use: > /domains/{domainName}/entities + +**Example:** Get all entities in the *RAN* domain: + +:: + + GET https:///topology-inventory//domains/RAN/entities + +To get a list of all available entity types in a specified domain name, +use: > /domains/{domainName}/entity-types + +**Example:** Get all entity types in the *RAN* domain: + +:: + + GET https:///topology-inventory//domains/RAN/entity-types + +To get a list of all available relationship types in a specified domain +name, use: > /domains/{domainName}/relationship-types + +**Example:** Get all relationship types in the *RAN* domain: + +:: + + GET https:///topology-inventory//domains/RAN/relationship-types + +Querying entities and relationships +----------------------------------- + +Use the *targetFilter* parameter to narrow down the fields to return. To +filter the results which match a given criteria, use the *scopeFilter*. +Think of it as an SQL statement, where the *targetFilter* is the SELECT, +and the *scopeFilter* is the WHERE tag. + +A detailed explanation about the *targetFilter* and *scopeFilter* +parameters can be found in :doc:`Supported filter options `. + +**Example:** + +In this example, the user is only interested in NRCellDU entities. +Moreover, the user only wants those records that have sourceIds +containing “SubNetwork=Ireland”. These fields and filters can be defined +in the request as follows: + + **Parameters:** - **targetFilter:** /NRCellDU - **scopeFilter:** + /sourceIds[contains(@item,'SubNetwork=Ireland')] + +:: + + GET https:///topology-inventory//domains/RAN?targetFilter=/NRCellDU&scopeFilter=/sourceIds[contains(@item,'SubNetwork=Ireland')] + +.. + + **Note:** If the targetFilter is not used here, the result contains + all entities and relationships that matches the condition in the RAN + domain. diff --git a/docs/favicon.ico b/docs/favicon.ico new file mode 100644 index 0000000..00b0fd0 Binary files /dev/null and b/docs/favicon.ico differ diff --git a/docs/geographical-location-enrichment-api.rst b/docs/geographical-location-enrichment-api.rst new file mode 100644 index 0000000..1966fdc --- /dev/null +++ b/docs/geographical-location-enrichment-api.rst @@ -0,0 +1,484 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2024 Nordix Foundation. All rights Reserved +.. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved + +Geographical Location Enrichment API 1.0.0beta1.0 +################################################# + +Geographical Location Enrichment API to enrich topology with +geographical data. + +Operations +========== + +.. _Ingestion Create: + +PUB ``ingestionCreate`` Operation +--------------------------------- + +*Topology & Inventory entities and relationships can be created.* + +- Operation ID: ``Ingestion`` + +Operation on Topology Inventory and Exposure input topic. + +Message Topology CREATE ``ingestionCreate`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +*Creates components in topology.* + +- Message ID: ``create`` +- Content type: application/json + +CREATE Headers +^^^^^^^^^^^^^^ + ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| Name | Type | Description | Value | Constraints | Notes | ++================+========+===============================================================================================================================================+==============================+======================+=======================================+ +| (root) | object | - | - | - | **additional properties are allowed** | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| ce_id | string | Unique identifier for the event. | - | - | - | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| ce_source | string | Source of the CloudEvent. | - | format (`uri`) | - | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| ce_type | string | Event type. It can be one of topology-inventory-ingestion-merge, topology-inventory-ingestion-delete, or topology-inventory-ingestion-create. | - | - | - | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| content-type | string | Content-type of the data contained within the cloud event. It is application/json. | const (`"application/json"`) | - | - | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| ce_dataschema | string | URI representing the schema of the data. This references the event-specific yang schema. | - | format (`uri`) | - | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| ce_time | string | Event timestamp. | - | format (`date-time`) | - | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| ce_specversion | string | The version of the CloudEvents specification which the event uses. | const (`"1.0"`) | - | - | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ + +.. + + Examples of headers *(generated)* + +.. code:: json + + { + "ce_specversion": "1.0", + "ce_id": "a30e63c9-d29e-46ff-b99a-b63ed83fd233", + "ce_source": "dmi-plugin:nm-1", + "ce_type": "topology-inventory-ingestion-create", + "ce_time": "2023-06-12T09:05:00Z", + "content-type": "application/json", + "ce_dataschema": "topology-inventory-ingestion:events:create:1.0.0" + } + +CREATE Payload +^^^^^^^^^^^^^^ + ++------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Type | Description | ++==================================================================+===============+===========================================================================================================================================================================================================================================================================================================================================+ +| (root) | Object | - | ++------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| data | - | The data part consists of the actual topology data. It contains all the entities and their associated relationships. | ++------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| data.entities | Array | Entities are topology objects comprising of an id, consumer data, attributes and metadata for each. It contains the id only in case of delete cloud event. | ++------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| data.entities.: | Object | Entities schema is adherent to the entity types and attributes mentioned in the yang modules. For yang modules, see [Data Models][Data Models]. | ++------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| data.relationships | Array | Relationships comprising of an A-side and a B-side for each. The A-side is considered the originating side of the relationship; the B-side is considered the terminating side of the relationship. The order of A-side and B-side is of importance and MUST NOT be changed once defined. It contains the id only in case of delete event. | ++------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| data.relationships.: | Object | Relationship schema is adherent to the relationship types mentioned in the yang modules. For yang modules, see [Data Models][Data Models]. | ++------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + + Examples of payload *(generated)* + +.. code:: json + + { + "data": { + "entities": [ + { + "o-ran-smo-teiv-equipment:AntennaModule": [ + { + "id": "urn:oran:smo:teiv:AntennaModule=1", + "attributes": { + "antennaModelNumber": "1", + "mechanicalAntennaBearing": 50, + "mechanicalAntennaTilt": 10, + "positionWithinSector": "Unknown", + "totalTilt": 14, + "electricalAntennaTilt": 2, + "antennaBeamWidth": [ + 35, + 23, + 21 + ], + "geo-location": { + "latitude": 41.73297, + "longitude": -73.007696, + "height": 3000 + } + }, + "sourceIds": [ + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1,AntennaSubunit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=1,RetSubUnit=1" + ], + "metadata": { + "trustLevel": "RELIABLE" + } + } + ] + }, + { + "o-ran-smo-teiv-equipment:AntennaModule": [ + { + "id": "urn:oran:smo:teiv:AntennaModule=2", + "attributes": { + "antennaModelNumber": "2", + "mechanicalAntennaBearing": 61, + "mechanicalAntennaTilt": 21, + "positionWithinSector": "Unknown", + "totalTilt": 25, + "electricalAntennaTilt": 3, + "antennaBeamWidth": [ + 46, + 34, + 32 + ], + "geo-location": { + "latitude": 52.84308, + "longitude": -84.118707, + "height": 41111 + } + }, + "sourceIds": [ + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2,AntennaSubunit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=2,RetSubUnit=1" + ], + "metadata": { + "trustLevel": "RELIABLE" + } + } + ] + } + ], + "relationships": [ + { + "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ + { + "id": "urn:sha512:TlJDZWxsRFU6U3ViTmV0d29yaz1FdXJvcGUsU3ViTmV0d29yaz1JcmVs=", + "aSide": "urn:oran:smo:teiv:AntennaModule=1", + "bSide": "urn:oran:smo:teiv:Site=1" + } + ] + }, + { + "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ + { + "id": "urn:sha512:TlJDZWxsRFU6U3ViTmV0d29yaz1FdXJvcGUsU3ViTmV0d29yaz1JcmVsYW5kLE1lQ2=", + "aSide": "urn:oran:smo:teiv:AntennaModule=2", + "bSide": "urn:oran:smo:teiv:Site=2" + } + ] + } + ] + } + } + +.. _Ingestion Merge: + +PUB ``ingestionMerge`` Operation +-------------------------------- + +*Topology & Inventory entities and relationships can be updated.* + +- Operation ID: ``Ingestion`` + +Operation on Topology Inventory and Exposure input topic. + +Message Topology MERGE ``ingestionMerge`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +*Updates components in topology.* + +- Message ID: ``merge`` +- Content type: application/json + +MERGE Headers +^^^^^^^^^^^^^ + ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| Name | Type | Description | Value | Constraints | Notes | ++================+========+===============================================================================================================================================+==============================+======================+=======================================+ +| (root) | object | - | - | - | **additional properties are allowed** | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| ce_id | string | Unique identifier for the event. | - | - | - | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| ce_source | string | Source of the CloudEvent. | - | format (`uri`) | - | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| ce_type | string | Event type. It can be one of topology-inventory-ingestion-merge, topology-inventory-ingestion-delete, or topology-inventory-ingestion-create. | - | - | - | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| content-type | string | Content-type of the data contained within the cloud event. It is application/json. | const (`"application/json"`) | - | - | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| ce_dataschema | string | URI representing the schema of the data. This references the event-specific yang schema. | - | format (`uri`) | - | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| ce_time | string | Event timestamp. | - | format (`date-time`) | - | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| ce_specversion | string | The version of the CloudEvents specification which the event uses. | const (`"1.0"`) | - | - | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ + +.. + + Examples of headers *(generated)* + +.. code:: json + + + { + "ce_specversion": "1.0", + "ce_id": "a30e63c9-d29e-46ff-b99a-b63ed83fd234", + "ce_source": "dmi-plugin:nm-1", + "ce_type": "topology-inventory-ingestion-merge", + "ce_time": "2023-06-12T09:05:00Z", + "content-type": "application/json", + "ce_dataschema": "topology-inventory-ingestion:events:merge:1.0.0" + } + +MERGE Payload +^^^^^^^^^^^^^ + ++------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Type | Description | ++==================================================================+===============+===========================================================================================================================================================================================================================================================================================================================================+ +| (root) | Object | - | ++------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| data | - | The data part consists of the actual topology data. It contains all the entities and their associated relationships. | ++------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| data.entities | Array | Entities are topology objects comprising of an id, consumer data, attributes and metadata for each. It contains the id only in case of delete cloud event. | ++------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| data.entities.: | Object | Entities schema is adherent to the entity types and attributes mentioned in the yang modules. For yang modules, see [Data Models][Data Models]. | ++------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| data.relationships | Array | Relationships comprising of an A-side and a B-side for each. The A-side is considered the originating side of the relationship; the B-side is considered the terminating side of the relationship. The order of A-side and B-side is of importance and MUST NOT be changed once defined. It contains the id only in case of delete event. | ++------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| data.relationships.: | Object | Relationship schema is adherent to the relationship types mentioned in the yang modules. For yang modules, see [Data Models][Data Models]. | ++------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. + + Examples of payload *(generated)* + +.. code:: json + + { + "data": { + "entities": [ + { + "o-ran-smo-teiv-equipment:AntennaModule": [ + { + "id": "urn:oran:smo:teiv:AntennaModule=1", + "attributes": { + "antennaModelNumber": "1", + "mechanicalAntennaBearing": 50, + "mechanicalAntennaTilt": 10, + "positionWithinSector": "Unknown", + "totalTilt": 14, + "electricalAntennaTilt": 2, + "antennaBeamWidth": [ + 35, + 23, + 21 + ], + "geo-location": { + "latitude": 41.73297, + "longitude": -73.007696, + "height": 3000 + } + }, + "sourceIds": [ + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=1,AntennaSubunit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=1,RetSubUnit=1" + ], + "metadata": { + "trustLevel": "RELIABLE" + } + } + ] + }, + { + "o-ran-smo-teiv-equipment:AntennaModule": [ + { + "id": "urn:oran:smo:teiv:AntennaModule=2", + "attributes": { + "antennaModelNumber": "2", + "mechanicalAntennaBearing": 61, + "mechanicalAntennaTilt": 21, + "positionWithinSector": "Unknown", + "totalTilt": 25, + "electricalAntennaTilt": 3, + "antennaBeamWidth": [ + 46, + 34, + 32 + ], + "geo-location": { + "latitude": 52.84308, + "longitude": -84.118707, + "height": 41111 + } + }, + "sourceIds": [ + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaUnit=2,AntennaSubunit=1", + "urn:3gpp:dn:ManagedElement=NR01,Equipment=1,AntennaUnitGroup=1,AntennaNearUnit=2,RetSubUnit=1" + ], + "metadata": { + "trustLevel": "RELIABLE" + } + } + ] + } + ], + "relationships": [ + { + "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ + { + "id": "urn:sha512:TlJDZWxsRFU6U3ViTmV0d29yaz1FdXJvcGUsU3ViTmV0d29yaz1JcmVs=", + "aSide": "urn:oran:smo:teiv:AntennaModule=1", + "bSide": "urn:oran:smo:teiv:Site=1" + } + ] + }, + { + "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ + { + "id": "urn:sha512:TlJDZWxsRFU6U3ViTmV0d29yaz1FdXJvcGUsU3ViTmV0d29yaz1JcmVsYW5kLE1lQ2=", + "aSide": "urn:oran:smo:teiv:AntennaModule=2", + "bSide": "urn:oran:smo:teiv:Site=2" + } + ] + } + ] + } + } + +.. _Ingestion Delete: + +PUB ``ingestionDelete`` Operation +--------------------------------- + +*Topology & Inventory entities and relationships can be deleted.* + +- Operation ID: ``Ingestion`` + +Operation on Topology Inventory and Exposure input topic. + +Message Topology DELETE ``ingestionDelete`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +*Deletes components in topology.* + +- Message ID: ``delete`` +- Content type: application/json + +DELETE Headers +^^^^^^^^^^^^^^ + ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| Name | Type | Description | Value | Constraints | Notes | ++================+========+===============================================================================================================================================+==============================+======================+=======================================+ +| (root) | object | - | - | - | **additional properties are allowed** | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| ce_id | string | Unique identifier for the event. | - | - | - | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| ce_source | string | Source of the CloudEvent. | - | format (`uri`) | - | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| ce_type | string | Event type. It can be one of topology-inventory-ingestion-merge, topology-inventory-ingestion-delete, or topology-inventory-ingestion-create. | - | - | - | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| content-type | string | Content-type of the data contained within the cloud event. It is application/json. | const (`"application/json"`) | - | - | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| ce_dataschema | string | URI representing the schema of the data. This references the event-specific yang schema. | - | format (`uri`) | - | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| ce_time | string | Event timestamp. | - | format (`date-time`) | - | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ +| ce_specversion | string | The version of the CloudEvents specification which the event uses. | const (`"1.0"`) | - | - | ++----------------+--------+-----------------------------------------------------------------------------------------------------------------------------------------------+------------------------------+----------------------+---------------------------------------+ + +.. + + Examples of headers *(generated)* + +.. code:: json + + { + "ce_specversion": "1.0", + "ce_id": "a30e63c9-d29e-46ff-b99a-b63ed83fd235", + "ce_source": "dmi-plugin:nm-1", + "ce_type": "topology-inventory-ingestion-delete", + "ce_time": "2023-06-12T09:05:00Z", + "content-type": "application/json", + "ce_dataschema": "topology-inventory-ingestion:events:delete:1.0.0" + } + +DELETE Payload +^^^^^^^^^^^^^^ + ++------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Type | Description | ++==================================================================+===============+===========================================================================================================================================================================================================================================================================================================================================+ +| (root) | Object | - | ++------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| data | - | The data part consists of the actual topology data. It contains all the entities and their associated relationships. | ++------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| data.entities | Array | Entities are topology objects comprising of an id, consumer data, attributes and metadata for each. It contains the id only in case of delete cloud event. | ++------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| data.entities.: | Object | Entities schema is adherent to the entity types and attributes mentioned in the yang modules. For yang modules, see [Data Models][Data Models]. | ++------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| data.relationships | Array | Relationships comprising of an A-side and a B-side for each. The A-side is considered the originating side of the relationship; the B-side is considered the terminating side of the relationship. The order of A-side and B-side is of importance and MUST NOT be changed once defined. It contains the id only in case of delete event. | ++------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| data.relationships.: | Object | Relationship schema is adherent to the relationship types mentioned in the yang modules. For yang modules, see [Data Models][Data Models]. | ++------------------------------------------------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. + + Examples of payload *(generated)* + +.. code:: json + + { + "data": { + "entities": [ + { + "o-ran-smo-teiv-equipment:AntennaModule": [ + { + "id": "urn:oran:smo:teiv:AntennaModule=1" + } + ] + }, + { + "o-ran-smo-teiv-equipment:AntennaModule": [ + { + "id": "urn:oran:smo:teiv:AntennaModule=2" + } + ] + } + ], + "relationships": [ + { + "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ + { + "id": "urn:sha512:TlJDZWxsRFU6U3ViTmV0d29yaz1FdXJvcGUsU3ViTmV0d29yaz1JcmVs=" + } + ] + }, + { + "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ + { + "id": "urn:sha512:TlJDZWxsRFU6U3ViTmV0d29yaz1FdXJvcGUsU3ViTmV0d29yaz1JcmVsYW5kLE1lQ2=" + } + ] + } + ] + } + } \ No newline at end of file diff --git a/docs/geographical-location-enrichment-guide.rst b/docs/geographical-location-enrichment-guide.rst new file mode 100644 index 0000000..64edd13 --- /dev/null +++ b/docs/geographical-location-enrichment-guide.rst @@ -0,0 +1,237 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2024 Nordix Foundation. All rights Reserved +.. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved + +Geographical enrichment guide +############################# + +Geographical Enrichment Guide Overview +====================================== + +In this guide, we explore how to use the Geographical Location +Enrichment API to enrich Topology & Inventory with geographical data. + +Geographical enrichment +======================= + +Geographical enrichment is the adding, modifying, and removing of +geographical entities that supports geographical information. +Geographical entities are associated to topology data. The following +geographical entities support geographical enrichment: + +- Sector +- AntennaModule +- Site + +For information on the entity types and their supported relationships, +see the :doc:`Data Models `. + +The format of the geographical enrichment message is CloudEvents. +Topology & Inventory uses `CloudEvents +Kafka® `__ version +2.5.x. The link provides a sample CloudEvents implementation in Java®. +CloudEvents SDKs also supports other languages. See +`CloudEvents `__. + +The “data” element consists of the actual topology and inventory data. +It contains all the geographical entities and their associated +relationships in application/json format, and each entity and +relationships are represented in application/yang-data+json format. + +CloudEvents attributes are validated against the :doc:`Data Models +`. If there +is an unknown attribute in the CloudEvents, Topology & Inventory does +not drop the whole event but parses and persists only valid attributes, +and unknown parts are logged and ignored. If an empty or bad payload is +sent, the data is not persisted. + +The value of non-mandatory fields can be deleted by sending a merge +request to set it to null. Null means that the value is not set. + +Example of enrich Topology & Inventory with geographical data +------------------------------------------------------------- + +This example creates a new topology Site entity and a relationship +between the Site and an AntennaModule. Using the +:ref:`create schema ` +the data producer can create entities that support geographical +enrichment. Attributes with null means not set. + +.. code:: json + + { + "ce_specversion": "1.0", + "ce_id": "a30e63c9-d29e-46ff-b99a-b63ed83fd233", + "ce_source": "dmi-plugin:nm-1", + "ce_type": "topology-inventory-ingestion-create", + "ce_time": "2023-06-12T09:05:00Z", + "content-type": "application/json", + "ce_dataschema": "topology-inventory-ingestion:events:create:1.0.0", + "data": { + "entities": [ + { + "o-ran-smo-teiv-equipment:Site": [ + { + "id": "urn:o-ran:smo:teiv:sha512:Site=1F137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC153", + "attributes": { + "name": "Dublin", + "location": { + "geo-location": { + "latitude": 41.73297, + "longitude": -73.007696 + } + } + } + } + ] + }, + { + "o-ran-smo-teiv-equipment:AntennaModule": [ + { + "id": "urn:o-ran:smo:teiv:sha512:AntennaModule=1FEBF137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC15323F1906228E93CFA4A1DB37D50252B3AFE6AEC9860E2CEA4A77BB3A25C9EA45DEDA87E765", + "attributes": { + "geo-location": { + "latitude": 41.73297, + "longitude": -73.007696 + } + } + } + ] + } + ], + "relationships": [ + { + "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ + { + "id": "urn:o-ran:smo:teiv:sha512:ANTENNAMODULE_INSTALLED_AT_SITE=TlJDZWxsRFU6U3ViTmV0d29yaz1FdXJvcGUsU3ViTmV0d29yaz1JcmVs=", + "aSide": "urn:o-ran:smo:teiv:sha512:AntennaModule=1FEBF137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC15323F1906228E93CFA4A1DB37D50252B3AFE6AEC9860E2CEA4A77BB3A25C9EA45DEDA87E765", + "bSide": "urn:o-ran:smo:teiv:sha512:Site=1F137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC153" + } + ] + } + ] + } + } + +Example of modify enriched Topology & Inventory with geographical data +---------------------------------------------------------------------- + +This example updates an existing Site entity. Using the +:ref:`merge schema ` +the data producer can update entities that support geographical +enrichment. + +.. code:: json + + + { + "ce_specversion": "1.0", + "ce_id": "a30e63c9-d29e-46ff-b99a-b63ed83fd234", + "ce_source": "dmi-plugin:nm-1", + "ce_type": "topology-inventory-ingestion-merge", + "ce_time": "2023-06-12T09:05:00Z", + "content-type": "application/json", + "ce_dataschema": "topology-inventory-ingestion:events:merge:1.0.0", + "data": { + "entities": [ + { + "o-ran-smo-teiv-equipment:Site": [ + { + "id": "urn:o-ran:smo:teiv:sha512:Site=1F137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC153", + "attributes": { + "name": "Dublin", + "location": { + "geo-location": { + "latitude": 52.73297, + "longitude": -84.007696 + } + } + } + } + ] + }, + { + "o-ran-smo-teiv-equipment:AntennaModule": [ + { + "id": "urn:o-ran:smo:teiv:sha512:AntennaModule=1FEBF137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC15323F1906228E93CFA4A1DB37D50252B3AFE6AEC9860E2CEA4A77BB3A25C9EA45DEDA87E765", + "attributes": { + "geo-location": { + "latitude": 52.73297, + "longitude": -84.007696 + } + } + } + ] + } + ], + "relationships": [ + { + "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ + { + "id": "urn:o-ran:smo:teiv:sha512:ANTENNAMODULE_INSTALLED_AT_SITE=TlJDZWxsRFU6U3ViTmV0d29yaz1FdXJvcGUsU3ViTmV0d29yaz1JcmVs=", + "aSide": "urn:o-ran:smo:teiv:sha512:AntennaModule=1FEBF137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC15323F1906228E93CFA4A1DB37D50252B3AFE6AEC9860E2CEA4A77BB3A25C9EA45DEDA87E765", + "bSide": "urn:o-ran:smo:teiv:sha512:Site=1F137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC153" + } + ] + } + ] + } + } + +Example of delete enriched data from Topology & Inventory +--------------------------------------------------------- + +This example deletes a topology Site entity and its relationship to an +AntennaModule entity. Using the +:ref:`delete schema ` +the data producer can delete entities that support geographical +enrichment. + +.. code:: json + + { + "ce_specversion": "1.0", + "ce_id": "a30e63c9-d29e-46ff-b99a-b63ed83fd235", + "ce_source": "dmi-plugin:nm-1", + "ce_type": "topology-inventory-ingestion-delete", + "ce_time": "2023-06-12T09:05:00Z", + "content-type": "application/json", + "ce_dataschema": "topology-inventory-ingestion:events:delete:1.0.0", + "data": { + "entities" : [ + { + "o-ran-smo-teiv-equipment:Site": [ + { + "id": "urn:o-ran:smo:teiv:sha512:Site=1F137533843657E9E9DBE60DBD86B045A057DB6D04B6A07AC153" + } + ] + } + ], + "relationships": [ + { + "o-ran-smo-teiv-equipment:ANTENNAMODULE_INSTALLED_AT_SITE": [ + { + "id" : "urn:o-ran:smo:teiv:sha512:ANTENNAMODULE_INSTALLED_AT_SITE=TlJDZWxsRFU6U3ViTmV0d29yaz1FdXJvcGUsU3ViTmV0d29yaz1JcmVs=" + } + ] + } + ] + } + } + +How to create and produce an event +================================== + +To create and produce an event, you can use the `CloudEventBuilder.v1 +and +KafkaProducer `__. +The link provides a sample CloudEvents implementation in Java. +CloudEvents SDKs also supports other languages. See +`CloudEvents `__. + +Troubleshooting +=============== + +If CloudEvents were sent but no data was persisted, check validation +failures and logs. Update the CloudEvent based on the logs and send it again. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..f1568fd --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,23 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2024 Nordix Foundation. All rights Reserved +.. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved + +Topology Exposure & Inventory Overview +====================================== + +Topology & Inventory manages the representation of topology and +inventory resources in a suite of evolving vendor-agnostic data models +to share and operate on a common view of the topology. + +-------------- + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + ./developer-guide.rst + ./data-models-guide.rst + ./geographical-location-enrichment-guide.rst + ./geographical-location-enrichment-api.rst + ./supported-filter-options.rst diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt new file mode 100644 index 0000000..fb15e65 --- /dev/null +++ b/docs/requirements-docs.txt @@ -0,0 +1,6 @@ +tox +Sphinx +doc8 +docutils < 0.17 +lfdocs-conf +urllib3~=1.26.15 \ No newline at end of file diff --git a/docs/supported-filter-options.rst b/docs/supported-filter-options.rst new file mode 100644 index 0000000..c76f9a0 --- /dev/null +++ b/docs/supported-filter-options.rst @@ -0,0 +1,124 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. SPDX-License-Identifier: CC-BY-4.0 +.. Copyright (C) 2024 Nordix Foundation. All rights Reserved +.. Copyright (C) 2024 OpenInfra Foundation Europe. All Rights Reserved + +Supported filter options +======================== + +Using the filtering options, it is possible to define more specific +requests in case of several endpoints. To perform filtering, +*targetFilter* and *scopeFilter* parameters can be used in the path. + +Sample structure using target and scope filters: + +:: + + GET https:///topology-inventory//domains/?targetFilter=&scopeFilter= + +.. + + See :download:`Topology & Inventory + API <../teiv/src/main/resources/v1/topology-exposure-inventory-openapi.yaml>` + for all possible filter options and sample responses for each endpoint. + +Querying simple entities +------------------------ + + This functionality is supported by the following endpoints: + **/domains/{domainName}/entity-types/{entityTypeName}/entities** + +The *entityTypeName* is used as the root of the queries (from here +referred as RootObject). Every other object, either in *targetFilter* or +*scopeFilter*, has to relate to the RootObject. The queries are +constructed starting from the RootObject and all other objects are +joined to it. If there is no connection between the RootObject and the +other object(s), the query is not constructed. The RootObject still can +be retrieved and filtered using the /attributes. + ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+----------------+---------------------------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| Use case | domainName | entityTypeName | targetFilter | scopeFilter | Query result | ++======================================================================================================================================================================================================================================================================================================================================================================================================+============+================+=================================+=========================================================================================+=======================================================================================================================================+ +| To return the ids for all instances of the entityTypeName used in the query. | RAN | GNBDUFunction | | | All ids of every GNBDUFunction | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+----------------+---------------------------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| To return all attributes of every instance of the entityTypeName used in the query. | RAN | GNBDUFunction | /attributes | | All GNBDUFunctions with every attribute | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+----------------+---------------------------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| To return every instance of the entityTypeName used in the query, but only the attribute that was defined in the *targetFilter* parameter.
Note: The attribute must be a valid field of the object. | RAN | GNBDUFunction | /attributes(gNBId) | | All gNBIds of every GNBDUFunction | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+----------------+---------------------------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| To return every instance of the entityTypeName used in the query, but only the attributes that were defined in the *targetFilter* parameter.
Note: The attributes must be separated by a comma "," when using parenthesis "()". | RAN | GNBDUFunction | /attributes(gNBId, gNBIdLength) | | All gNBIds and gNBIdLengths of every GNBDUFunction | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+----------------+---------------------------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| To return the ids for all instances of the entityTypeName used in the query, that matches the given property in the *scopeFilter* parameter. | RAN | GNBDUFunction | | /sourceIds[contains (@item, 'SubNetwork=Ireland')] | Unique set of ids of GNBDUFunctions, where sourceIds contains *SubNetwork=Ireland* | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+----------------+---------------------------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| To return the ids for all instances of the entityTypeName used in the query, that matches the given attributes in the *scopeFilter* parameter.
Note: The attributes must be separated by a *AND* or *OR*". | RAN | GNBDUFunction | | /attributes [@gNBIdLength=3 and @gNBId=111] | Unique set of ids of GNBDUFunctions, where the gNBIdLength equals 3 and the gNBId equals 111 | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+----------------+---------------------------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ +| To return the ids for all instances of the entityTypeName used in the query, that satisfies one of the conditions in the *scopeFilter* parameter. A condition is a complete unit of *scopeFilter* parameter surrounded by square brackets.
Note: Multiple conditions can be given in the scopeFilter separated by a semicolon ";" to represent AND, or a pipe symbol "|" to represent OR. | RAN | GNBDUFunction | | /attributes [@gNBIdLength=3] | /sourceIds[contains (@item, 'SubNetwork=Ireland')] | Unique set of ids of GNBDUFunctions, where where the gNBIdLength equals 3 or the sourceIds contains an item with "SubNetwork=Ireland" | ++------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------+----------------+---------------------------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+ + + +Querying connected entities +--------------------------- + + This functionality is achieved using associations and is supported by + the following endpoints: + **/domains/{domainName}/entity-types/{entityTypeName}/entities** + +The *entityTypeName* is used as the root of the queries. + ++------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Use case | domainName | entityTypeName | targetFilter | scopeFilter | Query result | ++================================================================================================================================================+=============+================+==============+==================================================================================================================================================================================================================================================+===============================================================================================================================================================================================================================+ +| To return the ids for all instances of an entityTypeName related by an association. | REL_OAM_RAN | ENodeBFunction | | /managed-by-managedElement | All ENodeBFunction entities that are managed by any Managed Element. | ++------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| To return the ids for all instances of an entityTypeName related by an association to another entity specified by its *id*. | REL_OAM_RAN | ENodeBFunction | | /managed-by-managedElement [@id = 'urn\:3gpp:dn: ManagedElement=1'] | All ENodeBFunction entities that are managed by by the Managed Element *urn\:3gpp:dn: ManagedElement=1*. | ++------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| To return the attributes for all instances of an entityTypeName related by one or more associations to other entities specified by their *id*. | REL_OAM_RAN | ENodeBFunction | /attributes | /attributes [@enbId=1] ; /managed-by-managedElement [@id='urn\:3gpp:dn: ManagedElement=1'] | /managed-by-managedElement [@id='urn\:3gpp:dn: ManagedElement=2'] ; /provided-euTranCell [@id='urn\:3gpp:dn: ManagedElement=1, EUtranCell=2'] | All EnodeBFunction entities with enbId as *1* managed by the Managed Element *urn\:3gpp:dn: ManagedElement=1* or *urn\:3gpp:dn: ManagedElement=2*, and provides EuTranCell *urn\:3gpp:dn: ManagedElement=1, EUtranCell=2*. | ++------------------------------------------------------------------------------------------------------------------------------------------------+-------------+----------------+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + + +Querying entities for relationships +----------------------------------- + + This functionality is supported by the following endpoints: + **/domains/{domainName}/entity-types/{entityTypeName}/entities/{entityId}/relationships**\ + +The *entityTypeName* is used as the root of the queries. + ++--------------------------------------------------------------------------------------------------------------------+------------+----------------+-------------------------------------------------+--------------+---------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Use case | domainName | entityTypeName | entityId | targetFilter | scopeFilter | Query result | ++====================================================================================================================+============+================+=================================================+==============+=====================================================================+=======================================================================================================================================================================================================+ +| To return the relationships for a given entity specified by its id. | RAN | GNBDUFunction | urn\:3gpp:dn: ManagedElement=1, GNBDUFunction=1 | | | All relations for the GNBDUFunction with id *urn\:3gpp:dn: ManagedElement=1, GNBDUFunction=1*. | ++--------------------------------------------------------------------------------------------------------------------+------------+----------------+-------------------------------------------------+--------------+---------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| To return specific relationships for a given entity specified by its id. | RAN | GNBDUFunction | urn\:3gpp:dn: ManagedElement=1, GNBDUFunction=1 | | /MANAGEDELEMENT _MANAGES _GNBDUFUNCTION | All *MANAGEDELEMENT _MANAGES _GNBDUFUNCTION* relations for the GNBDUFunction with id *urn\:3gpp:dn: ManagedElement=1, GNBDUFunction=1*. | ++--------------------------------------------------------------------------------------------------------------------+------------+----------------+-------------------------------------------------+--------------+---------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| To return specific relationships for an entity specified by its id to another entity using its id and association. | RAN | GNBDUFunction | urn\:3gpp:dn: ManagedElement=1, GNBDUFunction=1 | | /managed-by-managedElement [@id = 'urn\:3gpp:dn: ManagedElement=1'] | All *MANAGEDELEMENT _MANAGES _GNBDUFUNCTION* relations for the GNBDUFunction with id *urn\:3gpp:dn: ManagedElement=1, GNBDUFunction=1* where the managed element is *urn\:3gpp:dn: ManagedElement=1*. | ++--------------------------------------------------------------------------------------------------------------------+------------+----------------+-------------------------------------------------+--------------+---------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + + +Querying on relationships +------------------------- + + This functionality is supported by the following endpoints: + **/domains/{domainName}/relationship-types/{relationshipTypeName}/relationships** + +Here, the *relationshipTypeName* is used as the root of the queries. + ++----------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------+--------------+-------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Use case | domainName | relationshipTypeName | targetFilter | scopeFilter | Query result | ++==========================================================================================================+=============+=========================================+==============+===================================================================+===============================================================================================================================================================+ +| To return all relationships for a specified relationship type. | REL_OAM_RAN | MANAGEDELEMENT _MANAGES _ENODEBFUNCTION | | | All MANAGEDELEMENT_MANAGES_ENODEBFUNCTION relationships. | ++----------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------+--------------+-------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| To return all relationships for a specified relationship type with a specified association to an entity. | REL_OAM_RAN | MANAGEDELEMENT _MANAGES _ENODEBFUNCTION | | /managed-by-managedElement [@id='urn\:3gpp:dn: ManagedElement=1'] | All MANAGEDELEMENT_MANAGES_ENODEBFUNCTION relationships having an association *managed-by-managedElement* to ManagedElement *urn\:3gpp:dn: ManagedElement=1*. | ++----------------------------------------------------------------------------------------------------------+-------------+-----------------------------------------+--------------+-------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------+ + + +.. + + To get a relationship with a specific id, use: + **/domains/{domainName}/relationship-types/{relationshipTypeName}/relationships/{relationshipId}** + +**Example:** Get the *MANAGEDELEMENT_MANAGES_ENODEBFUNCTION* +relationship with id *rel1* in the *REL_OAM_RAN* domain: + +:: + + GET https:///topology-inventory//domains/REL_OAM_RAN/relationship-types/MANAGEDELEMENT_MANAGES_ENODEBFUNCTION/relationships/rel1 diff --git a/teiv/src/main/resources/models/o-ran-smo-teiv-cloud-to-ran.yang b/teiv/src/main/resources/models/o-ran-smo-teiv-cloud-to-ran.yang index 8645592..da05846 100644 --- a/teiv/src/main/resources/models/o-ran-smo-teiv-cloud-to-ran.yang +++ b/teiv/src/main/resources/models/o-ran-smo-teiv-cloud-to-ran.yang @@ -16,10 +16,24 @@ module o-ran-smo-teiv-cloud-to-ran { description "RAN Cloud to RAN Logical topology model. + This model contains the RAN Cloud to RAN Logical topology relations. + Copyright (C) 2024 Ericsson Modifications Copyright (C) 2024 OpenInfra Foundation Europe - This model contains the RAN Cloud to RAN Logical topology relations"; + Licensed under the Apache License, Version 2.0 (the \"License\"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an \"AS IS\" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + SPDX-License-Identifier: Apache-2.0"; revision "2024-05-02" { description "Initial revision."; diff --git a/teiv/src/main/resources/models/o-ran-smo-teiv-cloud.yang b/teiv/src/main/resources/models/o-ran-smo-teiv-cloud.yang index ef93698..75456b4 100644 --- a/teiv/src/main/resources/models/o-ran-smo-teiv-cloud.yang +++ b/teiv/src/main/resources/models/o-ran-smo-teiv-cloud.yang @@ -17,12 +17,26 @@ module o-ran-smo-teiv-cloud { description "RAN Cloud topology model. + This model contains the topology entities and relations in the + RAN CLOUD domain, which comprises cloud infrastructure and + deployment aspects that can be used in the topology model. + Copyright (C) 2024 Ericsson Modifications Copyright (C) 2024 OpenInfra Foundation Europe - This model contains the topology entities and relations in the - RAN CLOUD domain, which comprises cloud infrastructure and - deployment aspects that can be used in the topology model."; + Licensed under the Apache License, Version 2.0 (the \"License\"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an \"AS IS\" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + SPDX-License-Identifier: Apache-2.0"; revision "2024-05-02" { description "Initial revision."; diff --git a/teiv/src/main/resources/models/o-ran-smo-teiv-common-yang-extensions.yang b/teiv/src/main/resources/models/o-ran-smo-teiv-common-yang-extensions.yang index 92344b0..1b66c59 100644 --- a/teiv/src/main/resources/models/o-ran-smo-teiv-common-yang-extensions.yang +++ b/teiv/src/main/resources/models/o-ran-smo-teiv-common-yang-extensions.yang @@ -9,11 +9,25 @@ module o-ran-smo-teiv-common-yang-extensions { description "Topology and Inventory YANG extensions model + This model contains extensions to the YANG language that topology and + inventory models will use to define and annotate types and relationships. + Copyright (C) 2024 Ericsson Modifications Copyright (C) 2024 OpenInfra Foundation Europe - This model contains extensions to the YANG language that topology and - inventory models will use to define and annotate types and relationships."; + Licensed under the Apache License, Version 2.0 (the \"License\"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an \"AS IS\" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + SPDX-License-Identifier: Apache-2.0"; revision "2024-05-02" { description "Initial revision."; diff --git a/teiv/src/main/resources/models/o-ran-smo-teiv-common-yang-types.yang b/teiv/src/main/resources/models/o-ran-smo-teiv-common-yang-types.yang index 1b15ce7..7aeef7e 100644 --- a/teiv/src/main/resources/models/o-ran-smo-teiv-common-yang-types.yang +++ b/teiv/src/main/resources/models/o-ran-smo-teiv-common-yang-types.yang @@ -13,11 +13,25 @@ module o-ran-smo-teiv-common-yang-types { description "Topology and Inventory common types model + This model contains re-usable data types that topology and inventory models + will frequently use as part of types and relationships. + Copyright (C) 2024 Ericsson Modifications Copyright (C) 2024 OpenInfra Foundation Europe - This model contains re-usable data types that topology and inventory models - will frequently use as part of types and relationships."; + Licensed under the Apache License, Version 2.0 (the \"License\"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an \"AS IS\" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + SPDX-License-Identifier: Apache-2.0"; revision "2024-05-02" { description "Initial revision."; diff --git a/teiv/src/main/resources/models/o-ran-smo-teiv-equipment-to-ran.yang b/teiv/src/main/resources/models/o-ran-smo-teiv-equipment-to-ran.yang index f518785..a676f50 100644 --- a/teiv/src/main/resources/models/o-ran-smo-teiv-equipment-to-ran.yang +++ b/teiv/src/main/resources/models/o-ran-smo-teiv-equipment-to-ran.yang @@ -17,11 +17,25 @@ module o-ran-smo-teiv-equipment-to-ran { description "RAN Equipment to Logical topology model. + This model contains the RAN Equipment to Logical topology + entities and relations. + Copyright (C) 2024 Ericsson Modifications Copyright (C) 2024 OpenInfra Foundation Europe - This model contains the RAN Equipment to Logical topology - entities and relations."; + Licensed under the Apache License, Version 2.0 (the \"License\"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an \"AS IS\" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + SPDX-License-Identifier: Apache-2.0"; revision "2024-05-02" { description "Initial revision."; diff --git a/teiv/src/main/resources/models/o-ran-smo-teiv-equipment.yang b/teiv/src/main/resources/models/o-ran-smo-teiv-equipment.yang index 9401f38..d231491 100644 --- a/teiv/src/main/resources/models/o-ran-smo-teiv-equipment.yang +++ b/teiv/src/main/resources/models/o-ran-smo-teiv-equipment.yang @@ -17,13 +17,27 @@ module o-ran-smo-teiv-equipment { description "RAN Equipment topology model. - Copyright (C) 2024 Ericsson - Modifications Copyright (C) 2024 OpenInfra Foundation Europe - This model contains the topology entities and relations in the RAN Equipment domain, which is modelled to understand the physical location of equipment such as antennas associated with a cell/carrier - and their relevant properties e.g. tilt, max power etc."; + and their relevant properties e.g. tilt, max power etc. + + Copyright (C) 2024 Ericsson + Modifications Copyright (C) 2024 OpenInfra Foundation Europe + + Licensed under the Apache License, Version 2.0 (the \"License\"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an \"AS IS\" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + SPDX-License-Identifier: Apache-2.0"; revision "2024-05-02" { description "Initial revision."; diff --git a/teiv/src/main/resources/models/o-ran-smo-teiv-oam-to-cloud.yang b/teiv/src/main/resources/models/o-ran-smo-teiv-oam-to-cloud.yang index 7d99b9d..8b318c7 100644 --- a/teiv/src/main/resources/models/o-ran-smo-teiv-oam-to-cloud.yang +++ b/teiv/src/main/resources/models/o-ran-smo-teiv-oam-to-cloud.yang @@ -16,10 +16,24 @@ module o-ran-smo-teiv-oam-to-cloud { description "RAN O&M to Cloud topology model. + This model contains the RAN O&M to Cloud topology relations + Copyright (C) 2024 Ericsson Modifications Copyright (C) 2024 OpenInfra Foundation Europe - - This model contains the RAN O&M to Cloud topology relations"; + + Licensed under the Apache License, Version 2.0 (the \"License\"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an \"AS IS\" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + SPDX-License-Identifier: Apache-2.0"; revision "2024-05-02" { description "Initial revision."; diff --git a/teiv/src/main/resources/models/o-ran-smo-teiv-oam-to-ran.yang b/teiv/src/main/resources/models/o-ran-smo-teiv-oam-to-ran.yang index fb166ff..4a03cdc 100644 --- a/teiv/src/main/resources/models/o-ran-smo-teiv-oam-to-ran.yang +++ b/teiv/src/main/resources/models/o-ran-smo-teiv-oam-to-ran.yang @@ -16,10 +16,24 @@ module o-ran-smo-teiv-oam-to-ran { description "RAN O&M to Logical topology model. + This model contains the RAN O&M to Logical topology relations + Copyright (C) 2024 Ericsson Modifications Copyright (C) 2024 OpenInfra Foundation Europe - - This model contains the RAN O&M to Logical topology relations"; + + Licensed under the Apache License, Version 2.0 (the \"License\"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an \"AS IS\" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + SPDX-License-Identifier: Apache-2.0"; revision "2024-05-02" { description "Initial revision."; diff --git a/teiv/src/main/resources/models/o-ran-smo-teiv-oam.yang b/teiv/src/main/resources/models/o-ran-smo-teiv-oam.yang index 4d34953..b439513 100644 --- a/teiv/src/main/resources/models/o-ran-smo-teiv-oam.yang +++ b/teiv/src/main/resources/models/o-ran-smo-teiv-oam.yang @@ -12,12 +12,26 @@ module o-ran-smo-teiv-oam { description "RAN O&M topology model. + This model contains the topology entities and relations in the + RAN O&M domain, which are intended to represent management systems + and management interfaces. + Copyright (C) 2024 Ericsson Modifications Copyright (C) 2024 OpenInfra Foundation Europe - This model contains the topology entities and relations in the - RAN O&M domain, which are intended to represent management systems - and management interfaces."; + Licensed under the Apache License, Version 2.0 (the \"License\"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an \"AS IS\" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + SPDX-License-Identifier: Apache-2.0"; revision "2024-05-02" { description "Initial revision."; diff --git a/teiv/src/main/resources/models/o-ran-smo-teiv-ran.yang b/teiv/src/main/resources/models/o-ran-smo-teiv-ran.yang index 7ddbcb9..3b3eeba 100644 --- a/teiv/src/main/resources/models/o-ran-smo-teiv-ran.yang +++ b/teiv/src/main/resources/models/o-ran-smo-teiv-ran.yang @@ -19,12 +19,26 @@ module o-ran-smo-teiv-ran { description "RAN Logical topology model. + This model contains the topology entities and relations in the + RAN Logical domain, which represents the functional capability + of the deployed RAN that are relevant to rApps use cases. + Copyright (C) 2024 Ericsson Modifications Copyright (C) 2024 OpenInfra Foundation Europe - This model contains the topology entities and relations in the - RAN Logical domain, which represents the functional capability - of the deployed RAN that are relevant to rApps use cases."; + Licensed under the Apache License, Version 2.0 (the \"License\"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an \"AS IS\" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + SPDX-License-Identifier: Apache-2.0"; revision "2024-05-02" { description "Initial revision."; diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..1d20dcd --- /dev/null +++ b/tox.ini @@ -0,0 +1,39 @@ +# ============LICENSE_START======================================================= +# Copyright (C) 2024 Ericsson +# Modifications Copyright (C) 2024 OpenInfra Foundation Europe +# ================================================================================ +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# SPDX-License-Identifier: Apache-2.0 +# ============LICENSE_END========================================================= + +[tox] +minversion = 4.0 +envlist = + docs, + docs-linkcheck, +skipsdist = true + +[testenv:docs] +basepython = python3 +deps = -r{toxinidir}/docs/requirements-docs.txt + +commands = + sphinx-build -W -b html -n -d {envtmpdir}/docs/doctrees ./docs/ {toxinidir}/docs/_build/html + echo "Generated docs available in {toxinidir}/docs/_build/html" +allowlist_externals = echo + +[testenv:docs-linkcheck] +basepython = python3 +deps = -r{toxinidir}/docs/requirements-docs.txt +commands = sphinx-build -W -b linkcheck -d {envtmpdir}/docs/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck \ No newline at end of file