Source links
Currently there are a number of source files needed to get a complete view of the AAI schema information:
- .xsd file in correct version: https://gerrit.onap.org/r/gitweb?p=aai/schema-service.git;a=tree;f=aai-schema/src/main/resources/onap/aai_schema;hb=d4f97e683cb971ceb7107beaaca628926156a4f6
- DB edge rules (.json) in correct version: https://gerrit.onap.org/r/gitweb?p=aai/schema-service.git;a=tree;f=aai-schema/src/main/resources/onap/dbedgerules;hb=3501e74711a2e91ce84d0b4cbc989738f96e0891
- Possibly also traversal information (.json): https://gerrit.onap.org/r/gitweb?p=aai/traversal.git;a=tree;f=aai-traversal/src/main/resources/schema/onap/query;hb=600abffda37ce3aba83024162dc7178d90b84c26
Auto-generated documentation of the AAI schema is the most complete at the moment (created by an OpenAPI/Swagger-like process).
- Source HTML file: https://wiki.onap.org/download/attachments/58229560/aai_swagger_v16.html?api=v2
- Stored here: AAI REST API Documentation - Dublin
- Originals stored in NEXUS:
- https://nexus.onap.org/service/local/repositories/releases/archive/org/onap/aai/schema-service/aai-schema/1.0.6/aai-schema-1.0.6.jar/!/onap/aai_swagger_html/aai_swagger_v16.html
- https://nexus.onap.org/service/local/repositories/releases/archive/org/onap/aai/schema-service/aai-schema/1.5.0/aai-schema-1.5.0.jar/!/onap/aai_swagger_html/aai_swagger_v16.html
Problems encountered when working with the AAI model structure:
- AAI uses RelationshipList as a generic linking class everywhere in the model – needs to be collapsed into the actual links
- AAI uses collection classes (ex. Pnfs as a collection for Pnf) that add no information – need to be filtered out
Ideas regarding how to do the reverse-engineering with a minimum of manual rework of the model (NOTE: most of these are still TODO):
- Convert XSD directly to UML – see Step-by-step to generate Papyrus UML model from XSD file. This method is inspired by these discussion threads:
- Generate UML model from OpenAPI (a.k.a. Swagger) YAML file, see https://github.com/opendata-for-all/wapiml and https://modeling-languages.com/openapi-to-uml/
- Generate UML model from JSON schema documents, see https://github.com/SOM-Research/jsonSchema-to-uml
Copy metadata in the .xsd file to XML tags that can be parsed by Ecore
- Combine the source files into a single XSD (XML schema file) using an XSLT script?
- Generate UML from OXM file, e.g. by model-browser script
4 Comments
Keong Lim
FYI, the XSD files are not the primary source of schema information in AAI. The XSD is generated from the OXM:
https://gerrit.onap.org/r/gitweb?p=aai/schema-service.git;a=tree;f=aai-schema/src/main/resources/onap/oxm;hb=HEAD
The EdgeRule files are important. Note that they have an overlap with the OXM files because sub-object containment relationships in the OXM also require "TREE" EdgeRules which are denoted by the "contains-other-v" property.
The Traversal custom queries are interesting from a usage perspective (there are clients of AAI find it useful to retrieve that information) but they do not define the schema, they only traverse what was defined above in the OXM and EdgeRules.
For comparison with other diagrams you may generate, please see also my one-off attempt to visualise the graph:
James Forsyth
Jacqueline Beaulac is the file created by eclipse posted somewhere, or tracked in gerrit?
William LaMont
I was able to generate/modify json file from aai_swagger_v16.yaml that I was able generate class diagram and apply OpenAPI profile in WAPIml
swagger.json
I wasn't able get yaml2json to work locally, so I used,
http://central.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.7/swagger-codegen-cli-2.4.7.jar
Rename swagger-codegen-cli-2.4.7.jar, swagger-codegen-cli.jar
java -jar swagger-codegen-cli.jar generate -i aai_swagger_v16.yaml -l swagger
And the resulting json file did not have patchDefinitions. So I updated the references
"$ref" : "#/patchDefinitions"
to
"$ref" : "#/definitions"
I found API references which repeated the same parameter twice would not properly load,
as in,
"/business/customers/customer/{global-customer-id}/service-subscriptions/service-subscription/{service-type}/service-instances/service-instance/{service-instance-id}/allotted-resources/allotted-resource/{id}/tunnel-xconnects/tunnel-xconnect/{id}
replacing the id references in tunnel-xconnect with id1, passed that failure
Two other failures that were identified in the error messages were
Invalid UTF-8 start byte 0x92
at [Source: java.io.FileInputStream@537c71aa; line: 52511, column: 71]
change this line,
"description" : "Aggregate route configs are used on the D2 IPE’s for the Voice services. In 1902, SDNC will create aggregate-route objects and write them to A&AI. \n###### Related Nodes\n- TO l3-network (PARENT of aggregate-route, aggregate-route BelongsTo l3-network, MANY2ONE)(4)\n\n-(4) IF this TO node is deleted, this AGGREGATE-ROUTE is DELETED also\n"
to
"description" : "Aggregate route configs are used on the D2 IPEs for the Voice services. In 1902, SDNC will create aggregate-route objects and write them to A&AI. \n###### Related Nodes\n- TO l3-network (PARENT of aggregate-route, aggregate-route BelongsTo l3-network, MANY2ONE)(4)\n\n-(4) IF this TO node is deleted, this AGGREGATE-ROUTE is DELETED also\n"
Invalid UTF-8 start byte 0x85
at [Source: java.io.FileInputStream@456d61b3; line: 60563, column: 57]
changed
"description" : "Design of zone [Medium/Large…]"
to
"description" : "Design of zone [Medium/Large]"
Keong Lim
William LaMont I believe the "[Medium/Large...]" text is in the description field of the OXM as literal text. It appears to contain the Unicode Ellipsis character https://www.fileformat.info/info/unicode/char/2026/index.htm
As Jacqueline Beaulac says, Microsoft Word automatically inserts this as a replacement character, but that's not the only way it could get in.
So the edit should occur in the original OXM files.
As for the "patchDefinitions" reference, should I include that in the code changes already proposed for AAI-2441 - Getting issue details... STATUS ?