Array in incorrectly formatted as containing "undefined"

[markgrand]

Swagger File

# REST interface for Bc4SC.
swagger: '2.0'

# Metadata about this specification
info:
  version: "0.1.0"
  title: Bc4SC REST interface
  contact:
    name: Mark Grand
    email: mark.grand@hcl.com
  license: 
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

# All communcations should be secured through https
schemes: ["https"]

################################################################################
#                                   Parameters                                 #
################################################################################
parameters:
  assetId:
    name: assetId
    in: body
    description: An asset identifier.
    required: true
    schema:
      $ref: '#/definitions/assetId'

  domain:
    name: x-domain
    in: header
    description: A domain name
    required: true
    type: string

  newAssetDescription:
    name: assetDescription
    in: body
    description: An asset description that does not include an creation time.
    required: true
    schema:
      $ref: '#/definitions/newAssetDescription'

  participant:
    name: x-participant
    in: header
    description: The uuid associated with blockchain certificate.
    required: true
    type: string
    format: uuid

  publicOrPrivate:
    name: x-public-or-private
    in: header
    description: Indicates if something is public or private. The value should be 'public' or 'private'
    type: string
    enum: 
      - public
        private

  signature:
    name: x-Ed25519-signature
    in: header
    description: The base64 encoded Ed25519 signature for this request. The signature is based on the resquest parameter or concatenation of parameters noted in the request description. The signature will be verified using the public key associated with the userId parameter of the same request. 
    required: true
    type: string
    format: byte

  userId:
    name: x-user-id
    in: header
    description: The user ID associated with an blockchain participant.
    required: true
    type: string

  userInfo:
    name: user-info
    in: body
    description: The user information for enrolling a new user.
    required: true
    schema:
      $ref: '#/definitions/userInfo'

################################################################################
#                                           Paths                              #
################################################################################
paths:
  # Path for managing enrollments
  /registrar/enroll:
    # This is a HTTP operation
    post:
      # Brief description. Note: you can use markdown
      summary: Request to enroll an entity as a participant in the blockchain.
      # Describe this verb here. Note: you can use markdown
      description:
        Request the enrollment of the entity described by the JSON object in the request body as a blockchain participant. The JSON object must identify an entity not already enrolled as a blockchain participant.

        The JSON object should be constructed by a client library that is also responsibile for generating the necessary public-private key pairs.

        Calling this is the first step of a two step process. This operation begins the process of enrolling the subject of the given certificate. Approval of the enrollment may be fast or a lengthy process, depending on the configuration of the blockchain. Use the GET operation to check on the status of the approval process.

      parameters: 
        - $ref : '#/parameters/userInfo'

      # Expected responses for this operation:
      responses:
        # success response codes
        202:
          description: 
            Successful enrollment request.  Status and outcome of the approval process will be
            obtainable through the GET operation.
        # Failure response codes
        400:
          description:
            The request body could not be parsed into a JSON object with the required structure.
        409:
          description:
            The entity identified by the JSON object is already enrolled as a participant in the blockchain.
        423:
          description:
             There is already a pending enrollment request for the entity identified by the JSON object. 
        451:
          description:
            The entity identified by the JSON object is barred from participation in this blockchain. This could be for legal reasons.

    get:
      summary: Get the status and result of approving an enrollment request
      description:
        Get the status and result of approving a previous request to enroll an entity and a blockchain participant. The request body should contain the same JSON object that was in the POST request that initiated the approval. The returned status code indicates if the request is still pending, succeeded or failed. 

        If the request was approved then the x-user-id header in the response contains the user id for the entity RSA encrypted using the public key in the JSON object. 

      parameters: 
        - $ref : '#/parameters/userInfo'

      responses: 
        # success response codes
        200:
          description:
            The enrollment request was rejected.  A future request may succeed.
        201:
          description:
            The enrollment request was approved and the entity is now enrolled. The response's x-user-id header will contain the entity's user ID, RSA encrypted using the entity's public key and then base64 encoded. 
          headers:
            x-user-id:
              description: The entity's user ID, RSA encrypted using the entity's public key and then base64 encoded.
              type: string
              format: byte
        204:
          description:
            The enrollment request is still pending.
        # failure response codes
        400:
          description:
            The request body could not be parsed into a JSON object with the required structure.
        404:
          description:
            There is no enrollment request for the entity identified by the JSON object.

    put:
      summary: Associate new user information and a new user ID with an entity.
      description:
        It is not currently possible for a user to ever change the public-private key pairs associated with their Bc4SC account. It is for this reason that user IDs are treated as a secret. 

        This request is the first step in updating user ID associated with a blockchain participant. It is also a way to update the contact information associated with a blockchain participant. 

        This request associates a new user ID with blockchain participant identified by the given x-user-id header value. The request body contains a JSON object similar to the one originally used to enroll the blockchain participant.

        The public key values in the JSON object must be the same as were used to enroll the blockchain participant, otherwise the JSON object will be considered invalid. The other information in the JSON object is used to update Bc4SC's metadata about the blockchain participant.

        The signature parameter is based on the JSON object concatenated to the user.

        The successful response to this contains a new user ID for the blockchain participant. The new user id is RSA encrypted with the blockchain participant's public key and then base64 encoded.

        After clients have switched over to using the use user ID. The DELETE operation should be used to retire the old user ID.

      parameters: 
        [ 
          {$ref : '#/parameters/userId' },
          {$ref : '#/parameters/signature' },
          {$ref : '#/parameters/userInfo' }
        ]   
      responses: 
        # success response codes
        200:
          description:
            Success. The blockchain participant's metadata was updated. The response body contains the blockchain participant's new user ID. 
          schema:
            type: string
            format: byte
          headers:
            x-user-id:
              description: The blockchain participant's new user ID, RSA encrypted using the entity's public key and then base64 encoded.
              type: string
              format: byte
        # failure response codes
        400:
          description:
            The request body could not be parsed into an JSON object having the required structure.
        403:
          description:
            This request failed because the given signature was not valid or because the given user ID is invalid or unauthorized for this request.

    delete:
      summary: Deactivate a user ID.
      description:
        The DELETE operation should be used to retire old user IDs for which a replacemtn has already been obtained with the PUT operation. After this request successfully completes, the given user ID will no longer be valid.

        The signature parameter is based on the user ID.

      parameters: 
        [ 
          {$ref : '#/parameters/userId' },
          {$ref : '#/parameters/signature' },
        ]   
      responses: 
        # success response codes
        200:
          description:
            The given user ID is no longer valid. 
          schema:
            type: string
            format: byte
          headers:
            x-user-id:
              description: The entity's user ID, RSA encrypted using the entity's public key and then base64 encoded.
              type: string
              format: byte
        # failure response codes
        400:
          description:
            The given user id is now deactivated.
        403:
          description:
            This request failed because the given signature was not valid or because the given user ID is invalid or unauthorized for this request.

  /registrar/domain:
    post:
      summary:
        Create an asset ID domain.
      description:
        Create the asset ID domain specified by the domain parameter. To allow blockchain participants to issue asset IDs without having any conflict with other blockchain participants, all asset IDs must be qualified by an asset ID domain.

        If the domain is public then any entity can create an asset with an ID qualified by this domain. If the domain is private then only the blockchain participant that created the domain can create assets in the domain.

        The signature parameter is based on the user ID concatenated to the domain.
      parameters: 
        [ 
          {$ref : '#/parameters/userId' },
          {$ref : '#/parameters/signature' },
          {$ref : '#/parameters/domain' },
          {$ref : '#/parameters/publicOrPrivate' }
        ]   

      responses: 
        # success response codes
        201:
          description:
            The domain was created. 
        # failure response codes
        403:
          description:
            This request failed because the given signature was not valid or because the given user ID is invalid or unauthorized for this request.
        409:
          description:
            The request failed because the requested asset ID domain already exists.

  /participant/metadata:
    get:
      summary: Get participant metadata.
      description:
        Get metadata for the blockchain participant identified by the user ID that is the value of the x-participant parameter. The results will include at least the participant's UUID. Additional inforation may be include if the user ID identified by the request is sufficiently privileged or is the  participant in question.

        The signature parameter is based on the value of the x-user-id parameter concanenated to the value of the x-participant parameter.
      parameters:
        [ 
          {$ref : '#/parameters/userId' },
          {$ref : '#/parameters/signature' },
          {$ref : '#/parameters/participant' },
        ]   
      responses: 
        # success response codes
        200:
          description:
            The participant's metadata is returned in the body of the response. 
          schema:
            $ref: '#/definitions/participantMetadata'

        # failure response codes
        403:
          description:
            This request failed because the given signature was not valid or because the given user ID is invalid or unauthorized for this request.
        404:
          description:
            The request failed because the value of the x-participant parameter does not identify a blockchain participant.

  /asset/create:
    post:
      description:
        This requests the creation of an asset in the blockchain. The asset is described in the body of the request. A separate GET operation is needed to query the outcome.

        The signature parameter is based on the asset description in the body of the request.
      parameters: 
        [ 
          {$ref : '#/parameters/userId' },
          {$ref : '#/parameters/signature' },
          {$ref : '#/parameters/newAssetDescription' },
        ]   
      responses:
        # success response codes
        200:
          description:
            The asset creation was requested.

        # failure response codes
        403:
          description:
            This request failed because the given signature was not valid or because the given user ID is invalid or unauthorized for this request.
        404:
          description:
            The request failed because the value of the x-participant parameter does not identify a blockchain participant.

    get:
      description:
        Get the details of an asset's creation in the blockchain.

        The signature parameter is based on the asset identifier in the body of the request.
      parameters: 
        [ 
          {$ref : '#/parameters/userId' },
          {$ref : '#/parameters/signature' },
          {$ref : '#/parameters/assetId' },
        ]   
      responses:
        # success response codes
        200:
          description:
            The asset creation request did not succeed. The body of the response may contain a human readable reason. 
          schema:
            type: string
        201:
          description:
            The asset creation request succeeded. An asset description that includes the creation time is in the body of the response. 
          schema:
            $ref: '#/definitions/assetDescription'
        204:
          description:
            The asset creation request is still pending. The outcome is not yet known.

        # failure response codes
        403:
          description:
            This request failed because the given signature was not valid or because the given user ID is invalid or unauthorized for this request.
        404:
          description:
            The request failed because the value of the x-participant parameter does not identify a blockchain participant.

################################################################################
#                                 Definitions                                  #
################################################################################
definitions:
  assetDescription:
    type: object
    description:
      A description of an asset.
    required:
      - id
      - creationTime
      - ownership
      - consumed
    properties:
      id:
        $ref: '#/definitions/assetId'
      creationTime:
        description:
          The time that the asset was created in the blockchain.
        type: string
        format: date-time
      data:
        description:
          A json object that contains arbitrary information about the asset.
        type: object
      ownership:
        description:
          An array that enumerates the fungible items that make up this asset by the ownership of each item. Items of like ownership are grouped together.
        type: array
        items:
          $ref: '#/definitions/ownershipQuantity'
        minItems: 1
      consumed:
        description:
          The quantity of the fungible assets that make up this assent that have been consumed (removed from the supply chain).
        type: integer

  assetId:
    type: object
    description:
      An asset's unique identifier assigned by the participant that created it.
    required:
      - domain
      - id
    properties:
      domain:
        description:
          This is a blockchain unique identifier that is used to distinguish between asset IDs created by different entities. Two different entities can each create an asset with the same ID and they will be distinct because they have different domains. 
        type: string
      id:
        description:
          An identifier that is unique within the given domain.
        type: string

  contactInformation:
    description: contact information
    type: object
    required:
      - contactType
      - id
    properties:
      id:
        type: string
        format: uuid
      contactType: 
        type: string
        enum:
          - billing
          - admin
          - legal
          - technical
          - other
      name:
        type: string
      phone:
        type: string
      email:
        type: string
        format: email
      address1:
        type: string
      address2:
        type: string
      address3:
        type: string
      city:
        description: city or locality
        type: string
      state:
        description: state, province or region.
        type: string
      postalCode: 
        type: string
      country:
        type: string

  newAssetDescription:
    type: object
    description:
      A description of an new asset that has not yet been created in the blockchain.
    required:
      - id
    properties:
      id:
        $ref: '#/definitions/assetId'
      data:
        description:
          A json object that contains arbitrary information about the asset.
        type: object
      quantity:
        description:
          The number of fungible items that constitute the asset. If this is not specified, it is assumed to be 1.
        type: integer

  ownershipQuantity:
    type: object
    description:
      Indicates how many fungible items of an asset a participant owns
    required: 
      - quantity
    properties:
      owners:
        description: The owners of the items quantified in this object who each have the authotity to transfer ownership.
        type: array
        items:
          type: string
          format: uuid
      thresholdOwners:
        description: The owners of the items quantified in this object who collectively have the authotity to transfer ownership when at least the threshold number of owners agree.
        type: object
        properties:
          threshold:
            description: The number of owners in the owners array who must agree for a trasnfer to happen.
            type: integer
            minimum: 1
          owners:
            description: The owners of the items quantified in this object who collectively have the authotity to transfer ownership.
            type: array
            items:
              type: string
              format: uuid
      quantity:
        description: The number of fungible items owned.
        type: integer

  participantMetadata:
    type: object
    description:
      Metadata describing a blockchain participant.
    required:
      - uuid
    properties:
      uuid:
        description: The UUID of the participant
        type: string
        format: uuid
      creationTime:
        description:
          The time that the participant was enrolled in the blockchain.
        type: string
        format: date-time

  userInfo:
    type: object
    description:
      The information about an entity that is used to enroll the entity as a blockchain participant.
    required:
      - identifier
      - contacts
      - publicKeys
    properties:
      identifier:
        type: object
        required:
          - dnsDomain
          - countryCode
          - organization
        properties:
          organization:
            description: The name of the organization that is applying to enroll as a participant in the blockchain. If a value is supplied for the organizationalUnit key, then this is the larger organization that organizational unit is part of. 
            type: string
          countryCode:
            description: The ISO 3166-1 two letter country code that identifies the country that the whose laws will govern the blockchain participant. To keep things clear, multi-national organizations should enroll their national organizational units as blockchain participants rather than enroll the global organization as a single participant. 
            type: string
            enum:
              - AF # Afghanistan
              - AX # Åland
              - AL # Albania
              - DZ # Algeria
              - AS # American
              - AD # Andorra
              - AO # Angola
              - AI # Anguilla
              - AQ # Antarctica
              - AG # Antigua
              - AR # Argentina
              - AM # Armenia
              - AW # Aruba
              - AU # Australia
              - AT # Austria
              - AZ # Azerbaijan
              - BS # Bahamas
              - BH # Bahrain
              - BD # Bangladesh
              - BB # Barbados
              - BY # Belarus
              - BE # Belgium
              - BZ # Belize
              - BJ # Benin
              - BM # Bermuda
              - BT # Bhutan
              - BO # Bolivia
              - BA # Bosnia
              - BW # Botswana
              - BV # Bouvet
              - BR # Brazil
              - IO # British
              - BN # Brunei
              - BG # Bulgaria
              - BF # Burkina
              - BI # Burundi
              - KH # Cambodia
              - CM # Cameroon
              - CA # Canada
              - CV # Cape
              - KY # Cayman
              - CF # Central
              - TD # Chad
              - CL # Chile
              - CN # China
              - CX # Christmas
              - CC # Cocos
              - CO # Colombia
              - KM # Comoros
              - CG # Congo
              - CD # Congo
              - CK # Cook
              - CR # Costa
              - CI # Cote
              - HR # Croatia
              - CU # Cuba
              - CY # Cyprus
              - CZ # Czech
              - DK # Denmark
              - DJ # Djibouti
              - DM # Dominica
              - DO # Dominican
              - EC # Ecuador
              - EG # Egypt
              - SV # El
              - GQ # Equatorial
              - ER # Eritrea
              - EE # Estonia
              - ET # Ethiopia
              - FK # Falkland
              - FO # Faroe
              - FJ # Fiji
              - FI # Finland
              - FR # France
              - GF # French
              - PF # French
              - TF # French
              - GA # Gabon
              - GM # Gambia
              - GE # Georgia
              - DE # Germany
              - GH # Ghana
              - GI # Gibraltar
              - GR # Greece
              - GL # Greenland
              - GD # Grenada
              - GP # Guadeloupe
              - GU # Guam
              - GT # Guatemala
              - GG # Guernsey
              - GN # Guinea
              - GW # Guinea
              - GY # Guyana
              - HT # Haiti
              - HM # Heard
              - VA # Holy
              - HN # Honduras
              - HK # Hong
              - HU # Hungary
              - IS # Iceland
              - IN # India
              - ID # Indonesia
              - IR # Iran
              - IQ # Iraq
              - IE # Ireland
              - IM # Isle
              - IL # Israel
              - IT # Italy
              - JM # Jamaica
              - JP # Japan
              - JE # Jersey
              - JO # Jordan
              - KZ # Kazakhstan
              - KE # Kenya
              - KI # Kiribati
              - KP # Democratic
              - KR # Korea
              - XK # Kosovo
              - KW # Kuwait
              - KG # Kyrgyzstan
              - LA # Lao
              - LV # Latvia
              - LB # Lebanon
              - LS # Lesotho
              - LR # Liberia
              - LY # Libyan
              - LI # Liechtenstein
              - LT # Lithuania
              - LU # Luxembourg
              - MO # Macao
              - MK # Macedonia
              - MG # Madagascar
              - MW # Malawi
              - MY # Malaysia
              - MV # Maldives
              - ML # Mali
              - MT # Malta
              - MH # Marshall Islands
              - MQ # Martinique
              - MR # Mauritania
              - MU # Mauritius
              - YT # Mayotte
              - MX # Mexico
              - FM # Micronesia
              - MD # Moldova
              - MC # Monaco
              - MN # Mongolia
              - ME # Montenegro
              - MS # Montserrat
              - MA # Morocco
              - MZ # Mozambique
              - MM # Myanmar
              - NA # Namibia
              - NR # Nauru
              - NP # Nepal
              - NL # Netherlands
              - AN # Netherlands Antiles
              - NC # New
              - NZ # New Zealand
              - NI # Nicaragua
              - NE # Niger
              - NG # Nigeria
              - NU # Niue
              - NF # Norfolk
              - MP # Northern
              - NO # Norway
              - OM # Oman
              - PK # Pakistan
              - PW # Palau
              - PS # Palestinian
              - PA # Panama
              - PG # Papua
              - PY # Paraguay
              - PE # Peru
              - PH # Philippines
              - PN # Pitcairn
              - PL # Poland
              - PT # Portugal
              - PR # Puerto
              - QA # Qatar
              - RE # Reunion
              - RO # Romania
              - RU # Russian
              - RW # Rwanda
              - SH # Saint
              - KN # Saint
              - LC # Saint
              - PM # Saint
              - VC # Saint
              - WS # Samoa
              - SM # San Marino
              - ST # Sao
              - SA # Saudi
              - SN # Senegal
              - RS # Serbia
              - SC # Seychelles
              - SL # Sierra
              - SG # Singapore
              - SK # Slovakia
              - SI # Slovenia
              - SB # Solomon
              - SO # Somalia
              - ZA # South
              - GS # South
              - ES # Spain
              - LK # Sri Lanka
              - SD # Sudan
              - SR # Suriname
              - SJ # Svalbard
              - SZ # Swaziland
              - SE # Sweden
              - CH # Switzerland
              - SY # Syrian
              - TW # Taiwan
              - TJ # Tajikistan
              - TZ # Tanzania
              - TH # Thailand
              - TL # Timor
              - TG # Togo
              - TK # Tokelau
              - TO # Tonga
              - TT # Trinidad
              - TN # Tunisia
              - TR # Turkey
              - TM # Turkmenistan
              - TC # Turks and Cacos Islands
              - TV # Tuvalu
              - UG # Uganda
              - UA # Ukraine
              - AE # United Arab Emirates
              - GB # United Kingdom
              - US # United States
              - UM # United
              - UY # Uruguay
              - UZ # Uzbekistan
              - VU # Vanuatu
              - VE # Venezuela
              - VN # Viet Nam
              - VG # Virgin
              - VI # Virgin Islands
              - WF # Wallis
              - EH # Western
              - YE # Yemen
              - ZM # Zambia
              - ZW # Zimbabwe
          organizationalUnit:
            description:
              The organizational unit of the given organization that is applying to enroll as a blockchain participant. If this is specified, it should identify a legal entity that is part of the organization identified by the organization key.
            type: string
          dnsDomain:
            description:
              The DNS domain associated with the entity applying to be a blockchain participant.
            type: string
      contacts:
        description:
          Contact information for the blockchain participant. At least 1 must be specified.
        type: array
        items:
          - $ref: '#/definitions/contactInformation'
        minItems: 1
      publicKeys:
        description:
          The public keys that will be needed for encryption and validating signatures.
        type: object
        required:
        - Ed25519PublicKey
        - RSAPublicKey
        properties:
          Ed25519PublicKey:
            type: string
            format: byte
          RSAPublicKey:
            type: string
            format: byte
      creationTime:
        description:
          The time that this JSON object was created.  createionTime will always be specified when user info is returned from the Bc4SC server. It is optional when passing user info to the server.
        type: string
        format: date-time
      expirationTime:
        description:
          The time that this JSON object will no longer be valid. This key is not returned by the Bc4SC server but is required when user info is passed to the Bc4SC server.

          This value should be freshly set to a time a few seconds in the future each time user info is passed to the Bc4SC server. This is a security measure that serves to provide security against replay attacks.
        type: string
        format: date-time

################################################################################
#                                    To Do                                     #
################################################################################
#
# Add a mechanism to authorize entities other than the creator of a private 
# domain to create assets in the domain
#
################################################################################```

* Version: 
* Browser/OS: 
Internet Explorer 11.0
**Issue**
On the formatted side of the screen the swagger editor incorrectly displays the type of the "contacts" key of the user-info parameter of the POST /registrar/enroll request. The array is specified with a non-empty items. If I click on the arrows to toggle display of the user-info parameter as JSON, I see the object in the items array. 

[webron]

The value of items itself cannot be an array. Remove the dash to render it as an object, and it should resolve correctly.