Should the ouput array have the mediaType defined, or should be JSON the default?

[francescoingv]

I am referring to the Draft 2.0 in example 9.5, listing 45

The property "arrayOutput" is defined as an array of integer.
However it is not defined the mediaType.

While in this specific case it is quite reasonable the output will be a JSON (e.g. [1,2,3]),
I wonder if this should be expected as the default, or if the contentMediaType should be added in the output description.

As an alternative the output of an array of numbers could be also returned as text/csv: 1,2,3
and in this case the description will have to include this information.

If the output description has in the schema description 'contentMediaType': 'text/csv',
should the client also be prepared to receive 'application/json' ?

I think that the above does not apply for inline input array, as input must be passed as JSON,
however it could be of interest where the input array is passed by reference.

[fmigneault]

ogcapi-processes/core/examples/json/ProcessDescription.json

Lines 243 to 252 in 4a4a1dc

	"arrayOutput": {
	"schema": {
	"type": "array",
	"minItems": 2,
	"maxItems": 10,
	"items": {
	"type": "integer"
	}
	}
	},

Because the schema itself is type: array, I think it is fair to consider JSON as the default media-type since the Execution content would itself be JSON. This is more an "inline data" representation. Technically, even literals (true, 1, 1.23, "abc") are also valid "JSON", but omit the mediaType mention as well to keep the definition succinct.

If other equivalent types were supported and auto-managed by the process, they would have to be specified:

{
  "outputs": {
    "arrayOutput": {
     "schema": { 
       "oneOf": [
         {
           "type": "array", 
           "minItems": 2, 
           "maxItems": 10, 
           "items": { 
             "type": "integer" 
           } 
         },
         {
            "type": "string",
            "contentMediaType": "application/x-yaml",
         },
         {
            "type": "string",
            "contentMediaType": "text/csv",
         },
         {
            "type": "string",
            "contentMediaType": "application/json",
         }
       ]
     } 
  }
}

If you think this is problematic and want to limit the ambiguous by-reference case, you can specify "valuePassing": ["byValue"] explicitly.
https://docs.ogc.org/DRAFTS/18-062r3.html#sc-value-passing

@pvretano
I think this is a relevant edge case that might be worth explicitly mentioning for clarity.

[francescoingv]

Thank you @fmigneault
but, as I understand, passing to the API the following two strings: "\"ab,cd\",fg-hz", "1,2,3"
your proposed input definition will validate both,
while the following definition should only validate: "1,2,3" (which is what I would expect):

{
  "outputs": {
    "arrayOutput": {
     "schema": { 
       "oneOf": [
         {
           "type": "array", 
           "minItems": 2, 
           "maxItems": 10, 
           "items": { 
             "type": "integer" 
           } 
           # default?  "contentMediaType": "application/json",
         },
         {
           "type": "array", 
           "minItems": 2, 
           "maxItems": 10, 
           "items": { 
             "type": "integer" 
           } 
           "contentMediaType": "application/x-yaml",
         },
         {
           "type": "array", 
           "minItems": 2, 
           "maxItems": 10, 
           "items": { 
             "type": "integer" 
           } 
           "contentMediaType": "text/csv",
         },
       ]
     } 
  }
}

[fmigneault]

I don't think this is the correct form. The contentMediaType is really designed for type: string.
https://json-schema.org/understanding-json-schema/reference/non_json_data
Using type: array (or others) causes an ambiguity on how to parse a non-string value.

The correct form needs to nest the schema in contentSchema if desired:

{
  "outputs": {
    "arrayOutput": {
     "schema": { 
       "oneOf": [
         {
           "type": "array", 
           "minItems": 2, 
           "maxItems": 10, 
           "items": { 
             "type": "integer" 
           } 
         },
         {
            "type": "string",
            "contentMediaType": "application/x-yaml",
            "contentSchema": {
               "type": "array", 
               "minItems": 2, 
               "maxItems": 10, 
               "items": { 
                 "type": "integer" 
               } 
            }
         },
         {
            "type": "string",
            "contentMediaType": "text/csv",
            "contentSchema": {
               "type": "array", 
               "minItems": 2, 
               "maxItems": 10, 
               "items": { 
                 "type": "integer" 
               } 
            }
         },
         {
            "type": "string",
            "contentMediaType": "application/json",
            "contentSchema": {
               "type": "array", 
               "minItems": 2, 
               "maxItems": 10, 
               "items": { 
                 "type": "integer" 
               } 
            }
         }
       ]
     } 
  }
}

As you can see, that can quickly become very verbose if there are a lot of media-types to support, but is permitted if you want to be very strict about it. It could be possible to reduce the schema using a combination of oneOf/allOf nesting, but it is important that a oneOf remains at the top to respect https://docs.ogc.org/DRAFTS/18-062r3.html#req_core_process-execute-input-inline-multiple-types

The specification is not really explicit currently about mixing contentMediaType and contentSchema to refine the specifiers applied to the format/encoding of the type: string.

@pvretano I think this could also be clarified to ensure correct usage. I would also suggest having another recommendation (or requirement?) indicating that, if only the contentMediaType is provided, the "by-value JSON data form" portion of the schema also applies to the retrieved by-reference contents. The idea of this being to keep the schema definition succinct and easily interpretable by clients.

[francescoingv]

Thank you @fmigneault for pointing to the JSON schema example.
I then understand that the followings are data array definitions (applicable to both input and output data) and corresponding data array contents.

Definition 1: data as JSON data:

  "inputs_or_outputs": {
    "array_1": {
      "schema": { 
        "type": "array", 
        "minItems": 2, 
        "maxItems": 10, 
        "items": { 
          "type": "integer" 
        } 
      }
    },

Content 1: data array will either be valueNoObject or qualifiedValue:
"array_1": [1, 2, 3]
or
"array_1": {"value": [1, 2, 3] }

Definition 2: data as string with JSON contentMediaType:

  "inputs_or_outputs": {
    "array_2": {
      "schema": { 
        "type": "string", 
        "contentMediaType": "application/json",
        "contentSchema": {
          "type": "array", 
          "minItems": 2, 
          "maxItems": 10, 
          "items": { 
            "type": "integer" 
          } 
        }
      }
    },

Content 2: data array should include the specification of the mediaType, therefore a qualifiedValue is required:
"array_2": {"value": "[1, 2, 3]", "mediaType": "application/json" }

Definition 3: data as string with csv contentMediaType:

  "inputs_or_outputs": {
    "array_3": {
      "schema": { 
        "type": "string", 
        "contentMediaType": "text/csv",
        "contentSchema": {
          "type": "array", 
          "minItems": 2, 
          "maxItems": 10, 
          "items": { 
            "type": "integer" 
          } 
        }
      }
    },

Content 3: data array should include the specification of the mediaType, therefore a qualifiedValue is required:
"array_3": {"value": "1,2,3", "mediaType": "text/csv" }

I also would expect that if the data is provided by-reference, the reference will return the corresponding Content X,
i.e.:

1. [1, 2, 3] or {"value": [1, 2, 3] }
2. {"value": "[1, 2, 3]", "mediaType": "application/json" }
3. {"value": "1,2,3", "mediaType": "text/csv" }

@pvretano
While I expect the Definition 2 and Definition 3 will not be extensively used, I think some examples should be present to avoid ambiguities were required/needed by the implementer.

@fmigneault may be that the proposed

recommendation (or requirement?)

is not required if the above is correct.

[francescoingv]

@fmigneault I probably made a mistake in the previous cases:
as Definition 2 and Definition 3 both describe only one possible mediaType for the string representing the data array, it should be legal to have the Content X as valueNoObject:
2. "[1, 2, 3]"
3. "1,2,3"

However I wonder if there could be issues in composing processes (workflows),
e.g. if a process receiving the above data produced as output were enabled to handle input strings using alternative mediaType,
then the process would not know how to handle this input.

The reason for not using definitions with alternatives in the previous cases,
is that the above definitions are not ambiguous having contentMediaType and contentSchema where applicable,
and a definition with alternatives is a matter of using oneOf and adding the desired alternative definitions.

[bpross-52n]

SWG Meeting from 2026-06-08: Add clarifying examples to Part 1, based on the discussion in this issue.