Issue:
NCMP has an inconsistency between the JSON supplied/received and what exists in the database. This is producing issues such as those related to CM Handle querying.
| Create a CM Handle | Get a CM Handle | Query CM Handle | |
|---|---|---|---|
| URI | POST: http://localhost:8883/ncmpInventory/v1/ch | GET: http://localhost:8883/ncmp/v1/ch/CmHandle1 | |
| JSON BODY | { "dmiPlugin": "http://{{WSL IP}}:8783", "createdCmHandles": [ { "cmHandle": "CmHandle1", "cmHandleProperties": { "Books": "Sci-Fi Book" }, "publicCmHandleProperties": { "Color": "yellow", "Size": "medium", "Shape": "circle" } } ] } | N/A | { |
| JSON RESPONSE | N/A | { | [ |
| Inconsistencies |
|
|
|
| Description | Backwards Compatible | Breaks Convention | Overall CPS Convention impact | |
|---|---|---|---|---|
| 1 | Change OpenApi to kebab-casing | No - This would involve changing what is in red above. So changes to cmhandle registration and JSON responses. | Java stays in camelCasing and changes the json to kebab-casing | Would expect all endpoints to use kebab-casing: dataspace-name, schema-set. |
| 2 | Change dmi-registry to camelCasing | No - Would involve internal changes. Only changes to CM Handle API. | IEEE Guidelines state yang identifiers should be in kebab casing https://1.ieee802.org/yang-guidelines/ | Would expect all endpoints to use camel-casing: dataspaceName, schemaSet. Not what we do now |
Foreseen Impacts
Change OpenApi to kebab-casing
We would change components.yaml to kebab-casing
| components.yaml example | |
|---|---|
components.yaml current CmHandleCompositeState:
type: object
properties:
cmHandleState:
type: string
example: ADVISED
lockReason:
$ref: '#/components/schemas/lock-reason'
lastUpdateTime:
type: string
example: 2022-12-31T20:30:40.000+0000
dataSyncEnabled:
type: boolean
example: false
dataSyncState:
$ref: '#/components/schemas/dataStores'
| components.yaml future CmHandleCompositeState:
type: object
properties:
cm-handle-state:
type: string
example: ADVISED
lock-reason:
$ref: '#/components/schemas/lock-reason'
last-update-time:
type: string
example: 2022-12-31T20:30:40.000+0000
data-sync-enabled:
type: boolean
example: false
data-sync-state:
$ref: '#/components/schemas/dataStores'
|
This would change generated Java class:
| CmHandleCompositeState.java example | |
|---|---|
CmHandleCompositeState.java current public class CmHandleCompositeState {
@JsonProperty("cmHandleState")
private String cmHandleState = null;
@JsonProperty("lockReason")
private LockReason lockReason = null;
@JsonProperty("lastUpdateTime")
private String lastUpdateTime = null;
@JsonProperty("dataSyncEnabled")
private Boolean dataSyncEnabled = null;
@JsonProperty("dataSyncState")
private DataStores dataSyncState = null;
public CmHandleCompositeState cmHandleState(String cmHandleState) {
this.cmHandleState = cmHandleState;
return this;
}
...
| CmHandleCompositeState.java future public class CmHandleCompositeState {
@JsonProperty("cm-handle-state")
private String cmHandleState = null;
@JsonProperty("lock-reason")
private LockReason lockReason = null;
@JsonProperty("last-update-time")
private String lastUpdateTime = null;
@JsonProperty("data-sync-enabled")
private Boolean dataSyncEnabled = null;
@JsonProperty("data-sync-state")
private DataStores dataSyncState = null;
public CmHandleCompositeState cmHandleState(String cmHandleState) {
this.cmHandleState = cmHandleState;
return this;
}
...
|
And change JSON payload:
| JSON Payload | |
|---|---|
[
{
"cmHandle": "CmHandle1",
"publicCmHandleProperties": [
{
"Shape": "circle",
"Size": "medium",
"Color": "yellow"
}
],
"state": {
"cmHandleState": "LOCKED",
"lockReason": {
"reason": "LOCKED_MISBEHAVING",
"details": "some-details"
},
"lastUpdateTime": "2022-08-08T10:11:15.320+0000"
}
}
]
| [
{
"cm-handle": "CmHandle1",
"public-cm-handle-properties": [
{
"Size": "medium",
"Shape": "circle",
"Color": "yellow"
}
],
"state": {
"cm-handle-state": "LOCKED",
"lock-reason": {
"reason": "LOCKED_MISBEHAVING",
"details": "some-details"
},
"last-update-time": "2022-08-09T15:24:51.111+0000"
}
}
]
|
Change dmi-registry to camelCasing
Change the dmi-registry
| dmi-registry | |
|---|---|
list cm-handles {
key "id";
leaf id {
type string;
}
leaf dmi-service-name {
type string;
}
leaf dmi-data-service-name {
type string;
}
leaf dmi-model-service-name {
type string;
}
list additional-properties {
key "name";
leaf name {
type string;
}
leaf value {
type string;
}
}
list public-properties {
key "name";
leaf name {
type string;
}
leaf value {
type string;
}
}
container state {
leaf cm-handle-state {
type string;
}
container lock-reason {
uses LockReason;
}
leaf last-update-time {
type string;
}
leaf data-sync-enabled {
type boolean;
default "false";
}
container datastores {
uses Datastores;
}
}
}
}
}
| list cm-handles {
key "id";
leaf id {
type string;
}
leaf dmiServiceName {
type string;
}
leaf dmiDataServiceName {
type string;
}
leaf dmiModelServiceName {
type string;
}
list additionalProperties {
key "name";
leaf name {
type string;
}
leaf value {
type string;
}
}
list publicProperties {
key "name";
leaf name {
type string;
}
leaf value {
type string;
}
}
container state {
leaf cmHandleState {
type string;
}
container lockReason {
uses LockReason;
}
leaf lastUpdateTime {
type string;
}
leaf dataSyncEnabled {
type boolean;
default "false";
}
container datastores {
uses Datastores;
}
}
}
}
}
|
Would involve new Liquibase changeset and updating dmi-registry everywhere.
Java code changes related to CmHandleQueries
Open Questions
| Do we want to match the dmi-registry in its entirety? See below inconsistencies for CM Handle registration body: | ||
|---|---|---|
| CM Handle Registration Body | CM Handle Registration Body w/ Kebab-Casing | CM Handle Registration Body Conforming to dmi-registry |
| "cmHandle": "CmHandle1" | "cm-handle": "CmHandle1" | "id":"CmHandle1" |
"publicCmHandleProperties": [ ] | "public-cm-handle-properties": [ ] | "public-properties": [ ] |
| "cmHandleProperties": { "Books": "Sci-Fi Book" } | "cm-handle-properties": { "Books": "Sci-Fi Book" } | "additional-properties": { "Books": "Sci-Fi Book" } |