Fix RAML syntax

[adriendupuis]

Question	Answer
JIRA Ticket
Versions	4.5
Edition

RAML syntax

• In RAML, it's mandatory to type array items. There is two ways to do so:
  • the PHPDoc way:

    type: <type>[]

  • the RAML way:

    type: array
    items: <type>

• In RAML, like in YAML, a key can't have no value.

Disrespect of those rules generates errors when using a more recent RAML parser (see #1871).

Array items typing

I set items: mixed when I wasn't able to identify the expected types for the property items.

There is no associative arrays in JSON, only objects. Several arrays were in fact objects.

For names and descriptions properties, there are two ways:

• type: Value[] for the old way; ObjectStateGroup examples:

    <names>
        <value languageCode="eng-GB">Custom State</value>
    </names>

        "names": {
            "value": [
                {
                    "_languageCode": "eng-GB",
                    "#text": "Custom State"
                }
            ]
        },

• type: object for the new way; PaymentMethodUpdateStruct example

    <names>
        <eng-GB>Bank transfer (updated)</eng-GB>
    </names>

    "names": {
      "eng-GB": "Bank transfer (updated)"
    }

  Notice that this is not an array. PHP associative arrays are objects in JSON.
  I do not know how to describe the property of this object as their keys are dynamics, they depends on client's needed languages.
  What is the way to write this in XML?

Some types aren't used an may not need further investigation. "Unused" means that there is no REST route declaring type: <type> in its body or responses ("direct usage"), and there is no used other type using it for its properties ("indirect usage").

Updated types

• ContentTypeUpdateStruct (unused)
• CreateStruct (unused)
• Criterion: Could values be more detailed than items: mixed?
• FieldDefinitionCreateStruct (unused)
• FieldDefinitionUpdateStruct (unused)
• Language: constant ALL can't be a part of the response
• Message (unused)
• Notification (unused)
• Plural (unused)
• UrlAlias: path property typed as string.
• ValueObject (unused)
• ContentTypeCreate: names and descriptions are Value[] (see ContentTypeCreate.xml.example).
• ContentTypeUpdate: names and descriptions are Value[].
• CatalogCreate: names and descriptions are object (see CatalogCreate.json.example).
• CatalogUpdate: names and descriptions are object.
• AttributeGroupCreate: there is no languages property; Even if the parsed value has it, the input parser doesn't treat it.
• AttributeGroupUpdate: idem.
• Attribute: options seems to be an object; the main example has an empty array but ProductVariant example use an object as options in its DiscriminatorAttributesList; classes may help: Attribute ← AttributeDefinitionInterface ← OptionsBag which seems to be a key-value object.
• AttributeCreate: names and descriptions are object, options isn't clear.
• AttributeUpdate: idem.
• CustomerGroupCreate: names and descriptions are object.
• CustomerGroupUpdate: names is an object; languages doesn't exist.
• ProductListGet: languages is an array of strings (language codes as strings).
• ProductGet: idem.
• ProductCreate: attributes might be an array of objects.
• ProductUpdate: idem.
• ProductVariant: DiscriminatorAttributesList is an array of Attribute
• ProductVariantCreate: attributes should be an object as there is no associative array in JSON; I set it as a mixed[] to fit with the description but it should be discussed.
• ProductVariantGenerate: idem
• ProductVariantUpdate: idem
• TaxonomyEntry: names might not exist. There is a names in the PHP API contract but I see none in the REST API output.
• TaxonomyEntryUpdateStruct (unused)
• Order: context is an object.
• OrderItem: idem.
• PaymentMethodUpdateStruct: options might be an object, I left mixed[]. Why this not called PaymentMethodUpdateStructParser?

Checklist

• Text renders correctly
• Text has been checked with vale
• Description metadata is up to date
• Redirects cover removed/moved pages
• Code samples are working
• PHP code samples have been fixed with PHP CS fixer
• Added link to this PR in relevant JIRA ticket or code PR