Potential type mis-match between type definitions and examples.

[ferrywlto]

Problem

In the schema definition excerpt below, it could only be an integer or FeatureBreakdown:

"consumedService": {
  "additionalProperties": {
    "oneOf": [
      {
        "$ref": "#/components/schemas/LicenseReport.FeatureBreakdown"
      },
      {
        "type": "integer",
        "format": "int32"
      }
    ]
  },
  "description": "Usage telemetry retrieved for the service to indicate if the specific principal is consuming the service or not, regardless of license status.",
  "type": "object"
}

Taking a portion of LicenseReport.LicenseData examples:

"consumedService": {
  "eec0eb4f-6444-4f95-aba0-50c24d67f998": {
    "Conditional Access": true,
    "Access Review": false,
    "Entitlement Management": false,
    "Identity Protection": true
  },
  "41781fb2-bc02-4b7c-bd55-b576c07bb09d": {
    "Conditional Access": true,
    "Dynamic Group": false,
    "Group Naming": true,
    "On-Prem SSPR": false,
    "Group Expiration": true,
    "Provisioning Engine": true,
    "Enterprise State Roaming": false
  },
  "4b0d28f2-c1ce-48ae-a7d2-1caaa7825891": null,
  "c90f1a25-e6cd-4163-ac6c-ca7616c585a9": null
}

However we can see that the value of a key can either be null or FeatureBreakdown. Throughout the whole specification file, all examples are setting the value of the keys to null if not a FeatureBreakdown object. This does not match the type definition.

Question

Are the examples or the type definitions the source of truth?

Suggestion

If the examples are the source of truth, we should update the type definition as below instead of using integer:

"consumedService": {
  "additionalProperties": {
    "oneOf": [
      { "$ref": "#/components/schemas/LicenseReport.FeatureBreakdown" },
      { "type": "null" }
    ]
  },
  "description": "Usage telemetry retrieved for the service ...",
  "type": "object"
}

Or if the type definitions are correct, we should update all examples to integer instead of null to avoid confusions.

"consumedService": {
  "eec0eb4f-6444-4f95-aba0-50c24d67f998": {
    "Conditional Access": true,
    "Access Review": false,
    "Entitlement Management": false,
    "Identity Protection": true
  },
  "41781fb2-bc02-4b7c-bd55-b576c07bb09d": {
    "Conditional Access": true,
    "Dynamic Group": false,
    "Group Naming": true,
    "On-Prem SSPR": false,
    "Group Expiration": true,
    "Provisioning Engine": true,
    "Enterprise State Roaming": false
  },
  "4b0d28f2-c1ce-48ae-a7d2-1caaa7825891": 0,
  "c90f1a25-e6cd-4163-ac6c-ca7616c585a9": 0
}

@elliot-huffman @pasha-zayko May you confirm about it?

[elliot-huffman]

The servicePlan ID values can be:

Record<string & tags.Format<'uuid'>, FeatureBreakdown | number | null>;

The guid can have null, number or a feature breakdown.

[ferrywlto]

Got it. I will update the type definitions as below:

"consumedService": {
  "additionalProperties": {
    "oneOf": [
      {
        "$ref": "#/components/schemas/LicenseReport.FeatureBreakdown"
      },
      {
        "type": "integer",
        "format": "int32",
        "examples": [0]
      },
      { 
        "type": "null"
      }
    ]
  },
  "description": "Usage telemetry retrieved for the service to indicate if the specific principal is consuming the service or not, regardless of license status.",
  "type": "object",
}

[ferrywlto]

The same will applies to assignedLicense and similar fields as well for other potential type mis-matches.

This justification was according to type definition in code:

 'assignedLicense': Record<string & tags.Format<'uuid'>, number | null>;

From:

"assignedLicense": {
  "additionalProperties": {
        "type": "integer",
        "examples": [0]
  },
  "description": "License assignment on the specified principal.",
  "type": "object"
},

To:

"assignedLicense": {
  "additionalProperties": {
    "oneOf": [
      {
        "type": "integer",
        "examples": [0]
      },
      { 
        "type": "null"
      }
    ]
  },
  "description": "License assignment on the specified principal.",
  "type": "object"
},

[ferrywlto]

Further potential type mismatch:

In database schema, the architecture version was defined as string:

'shieldArchitectureVersion': {
  'allowNull': false,
  'type': DataTypes.TEXT
},
'shieldCoreVersion': {
  'allowNull': false,
  'type': DataTypes.TEXT
},

However in SHIELD.json, the architecture version was defined as number:

"properties": {
  "archSpecVersion": {
    "description": "An incrementing number that describes the version of the architecture specification that the API supports.",
    "examples": [123],
    "type": "number"
  },
  "deployedArchVersion": {
    "description": "The version of the architecture specification that is currently deployed.",
    "examples": [25],
    "type": "number"
  }
},

In Data-Gateway.json, the data type is correct but it is believed the type constraint is not correct.

"shieldArchitectureVersion": {
  "description": "Version number of the architecture that is deployed.",
  "examples": ["27"],
  "type": "string",
  "minimum": 1
},

For string, the constraint should be minLength instead of minimum.