Expressing arrays of a fixed (non-inherited) type

[kylef]

In MSON, it's not possible to express arrays which MUST contain a certain type of element. But the contents of the array does not have fixed values.

For example, I might want to describe a data structure which is an array of User objects. Where the array SHOULD only contain User objects, and other types of items inside the array are not valid.

In JSON Schema, I can represent this as follows:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "members": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "username": {
            "type": "string"
          }
        }
      }
    }
  }
}

Where I have a JSON Structure as follows, which validates using the previous schema:

{
  "name": "Blueprint Team",
  "members": [
     { "username": "kyle" }
   ]
}

However, a user without a username wouldn't validate:

{
  "name": "Blueprint Team",
  "members": [
     { "name": "Kyle" }
   ]
}

---

It should be possible to express what I have outlined above in API Blueprint / MSON. For example, I may intend to describe an array of User with the following blueprint:

## Team List [/teams]
### Create Team [POST]

+ Request (application/json)
    + Attributes
        + name: Blueprint Team
        + members (array[User])

+ Response 202

## Data Structures
### User

+ username: kyle

However, given the MSON specification array[User] does not mean an array of only User. But instead, an array which MAY contain User which ultimately means generated JSON Schema's cannot say that the array MUST contain ONLY User.

[w-vi]

I was thinking about it a bit and if we for need to keep the original fixed meaning I would propose new attributes for the container like structures in MSON (array and object) typed and untyped Which basically say that when the given array is typed it is of certain type as in array of user objects or in case of object it means that the object cannot have additional properties so it expects only members of given name and type. This is basically saying in JSON Schema additionalProperties: false. By default everything is untyped.

[pksunkara]

There was a suggestion of local-fixed by @goganchic in Blueprint slack channel.

[zdne]

I agree with @w-vi tho I ponder about clarity and proper keyword name. Most descriptive would be fixed-type, runner ups are final, freeze and const however since our fixed fixes both value and type and affects essentially only the type definition I really think <final|freeze|const|fixed>-type would be the most descriptive...

[w-vi]

If I was to choose one of the @z proposals I would go for fixed-type as fixedwe already have and this is a special case of it, just fixing the type not the value.

[pksunkara]

fixed-type sounds good to me.

[goganchic]

I have found such enum https://github.com/apiaryio/snowcrash/blob/master/src/MSON.h#L135
All elements named like <attribute name>TypeAttribute, so if we'll call new attribute fixed-type it will be FixedTypeTypeAttribute in enum. Is it ok?

[w-vi]

That's why I came up with typed to have it different and still convey the meaning but I guess we can live with this strangely named enum.

[goganchic]

typed if fine to me

[goganchic]

@pksunkara I've implemented parsing of typed attribute and I need it to be merged into snowcrash library to make pull request to drafter.

[pksunkara]

Also, we need to add some text to the MSON Specification regarding this.

[goganchic]

Ok, I'll try

[w-vi]

Shall this still be open, when we are actually supporting this?

[pksunkara]

Nope. Closing this.