Inline binary input: always encoded base-64 ?

[francescoingv]

I am reading the current Draft version 2.0 of the specification.

In the Abstract:
The requirements specified in the OGC API — Processes Standard build on the OGC Web Processing Service (WPS) 2.0 Standard and specify a processing interface to communicate over a RESTful protocol using JSON encodings.

Then the input is expected to be passed using JSON encoding.

Before Listing 16:
In some cases, for example to pass through firewalls, binary input values need to be encoded in-line in an execute request as a string.

From the above I do infer that there are cases where binary input values don't need to be encoded in-line.
I wonder if it is correct.

From requirement 24:
The service SHALL support binary values encoded as base64-encoded strings.

However it says nothing about possibly supporting alternative encoding for inline binary input.
And I find no way the client can know of alternative accepted encoding when "contentEncoding": "binary" (e.g. Example 4).

Personally I understand there should not be alternatives to encoding base64 the in-line values defined as "type": "string", "contentEncoding": "binary".
Differently the client should be able to know about it.

I expect the specification "type": "string", "contentEncoding": "binary" is applicable only where values are passed by reference,
and it should apply to the referenced resource (e.g. a binary "image/tiff" file pointed by an URL),
but I find it hard to find such an information.
Even more: I would expect the content of a reference URL for a "binary" value passed as reference is not encoded (or SHALL NOT be encoded).

However, strictly reading requirement 26 - B, it would result in expecting the content of a binary value specified as a reference to be encoded base64.
Should be the binary value an exception?

Could you please help?

[fmigneault]

From the above I do infer that there are cases where binary input values don't need to be encoded in-line.
I wonder if it is correct.

I think the intent of the sentence is not really about binary or not, but about using inline or not (i.e.: using value in contrast to using href). In other words, the text simply hints that firewall rules (or any other technical reason really) that could make it difficult to access a "remote" href can instead leverage value (with binary or other content-type/encoding specified by the process) to provide the data directly to avoid any additional request checks when fetching that URI.

I expect the specification "type": "string", "contentEncoding": "binary" is applicable only where values are passed by reference,
and it should apply to the referenced resource (e.g. a binary "image/tiff" file pointed by an URL),

I don't think it is quite it. Data could still be passed by value or href either way.

It is more that the process description tells which one it will expect/accept if value is used. Therefore, while the file's data could be binary, it could be passed directly as the binary octets or pre-encoded to base64 representation as requested by the process, the assumption being that it would apply the necessary operations to retrieve the binary data back into a file (if that is what the "core processing" needs, e.g. passing it to a gdal call under the hood).

Therefore, href in the native binary media-type may still be used. Whether binary is used in that case depends on the registered media-type's definition/RFC.

• Similar explanation in Handling input/output binary values #580

I would expect the content of a reference URL for a "binary" value passed as reference is not encoded (or SHALL NOT be encoded)

Even if a file referenced by URL is binary natively, the corresponding value passed inline may be base64 pre-encoded if that is what the process needs. Inversely, a non-binary file may also be represented in base64 (e.g.: passing a literal embedded JSON string avoiding any \ to place within the execution JSON body). It is really just a transaction information that the process tells "I want contentEncoding representation if passing the data by value".

I think the requirements could be clarified. The binary, base64, base32, base16, etc. are all examples. I don't think there should be a particular encoding requirement. It is flexible as needed. The base64 examples are used for convenience given it is the most common one.

The important thing is that the processing engine applies the relevant decode handling (as necessary) to retrieve the data that would be found in the file. Whether the encoding aligns with whichever requirements the media-type might impose (if any) is entirely dependant of the media-type and what the processing engine needs to do with it.

[francescoingv]

@fmigneault

I think the intent of the sentence is not really about binary or not, but about using inline or not

Thank you, however I found the sentence misleading.
May i suggest to rephrase, stating something like "Binary values transmitted by value always need to be encoded in-line...",
instead of "In some cases, ..., binary input values need to be encoded in-line...".
Possibly also adding the reason for using value as opposed to href as you explained above.

It is more that the process description tells which one it will expect/accept if value is used. Therefore, while the file's data could be binary, it could be passed directly as the binary octets or pre-encoded to base64 representation as requested by the process, the assumption being that it would apply the necessary operations to retrieve the binary data back into a file (if that is what the "core processing" needs, e.g. passing it to a gdal call under the hood).

I am arguing on the specific case the process description state the input value is "type": "string", "contentEncoding": "binary".
As an example (Example 4):

"schema": {
    "type": "string",
    "contentEncoding": "binary",
    "contentMediaType": "image/tiff; application=geotiff"
}

I don't see any representation as requested by the process,
and I don't see any way the client can imagine the server may support any other representation, but encoded base64 (which is required by requirement 24.

I know the answer to #580
It states the client can submit "value": "<blob>", "encoding": "base32", but it is not clear how the client should know the server will accept it.
Is it a matter of try-and-fail ?

I would expect the content of a reference URL for a "binary" value passed as reference is not encoded (or SHALL NOT be encoded)

I'll try to make it more clear:
if I have the above definition (Example 4) and will pass the input by reference as:

"imagesInput": 
  {
    "href": "https://www.someserver.com/myImage.tiff",
    "type": "image/tiff; application=geotiff"
  }

I expect "https://www.someserver.com/myImage.tiff" will resolve to a binary, not to an encoded string.

If it is correct then the following issue apply:

However, strictly reading requirement 26 - B, it would result in expecting the content of a binary value specified as a reference to be encoded base64.

You say:

The base64 examples are used for convenience given it is the most common one.

I think the base64 examples are used following the requirement 24: any other encoding is not mandatory.

The important thing is that the processing engine applies the relevant decode handling

I believe it is also important the client are allowed to know the supported encoding when sending in-line binary string values.

[fmigneault]

It states the client can submit "value": "<blob>", "encoding": "base32", but it is not clear how the client should know the server will accept it.
Is it a matter of try-and-fail ?

If the process indicated the following:

{
  "inputs": {
    "image": {
      "schema": {
        "oneOf": [
          {
            "type": "string",
            "contentEncoding": "binary",
            "contentMediaType": "image/tiff; application=geotiff"
          },
          {
            "type": "string",
            "contentEncoding": "base64",
            "contentMediaType": "image/tiff; application=geotiff"
          }
        ]
      }
    }
  }
}

Then its execution request allows either binary or base64. From that perspective, it should disallow base32 since it is not one of the supported input encodings. There is no reason treat validation of the string encoding any differently than validating the media-type, just like submitting a PNG instead of the expected GeoTIFF should be refused.

"imagesInput": 
  {
    "href": "https://www.someserver.com/myImage.tiff",
    "type": "image/tiff; application=geotiff"
  }

I expect "someserver.com/myImage.tiff" will resolve to a binary, not to an encoded string.

Indeed, that is correct.

Because there is no need to pass an inline string in this case (the binary data is obtained directly in the native format specified by the type), there is no contentEncoding involved. The fact that it is binary or not is entirely based on the media-type. If another encoding that binary was used in that file, it would not be a image/tiff; application=geotiff but a image/tiff; application=geotiff; encoding=base64 or some other variant. The contentEncoding is necessary to disambiguate the string (when passed by value, not href) since the binary data goes under some transformation to be passed inline. This transformation is not needed by reference.

[francescoingv]

Then I understand that, according to requirement 24

• when a schema is defined with:

    "schema": {
        "type": "string",
        "contentEncoding": "binary",
        "contentMediaType": <my_mediaType>
    }

the following is the validation the input should pass:

    "schema": {
        "oneOf": [
          {
            "type": "string",
            "contentEncoding": "binary",
            "contentMediaType": <my_mediaType>
          },
          {
            "type": "string",
            "contentEncoding": "base64",
            "contentMediaType": <my_mediaType>
          }
        ]
    }

• if the schema is defined with:

    "schema": {
        "oneOf": [
          {
            "type": "string",
            "contentEncoding": "binary",
            "contentMediaType": <my_mediaType>
          },
          {
            "type": "string",
            "contentEncoding": <any_but_base64>,
            "contentMediaType": <my_mediaType>
          }
        ]
    }

the following is the validation the input should pass:

    "schema": {
        "oneOf": [
          {
            "type": "string",
            "contentEncoding": "binary",
            "contentMediaType": <my_mediaType>
          },
          {
            "type": "string",
            "contentEncoding": <any_but_base64>,
            "contentMediaType": <my_mediaType>
          },
          {
            "type": "string",
            "contentEncoding": "base64",
            "contentMediaType": <my_mediaType>
          }
        ]
    }

It would also solve the question I initially raised about strictly interpreting requirement 26 - B.

I understand it is not possible to formalize the above rule in a .yaml file,
however (if the above is correct) I think it would be valuable at least to make it explicit in the document.

[fmigneault]

@francescoingv I agree. It would be better to mention these examples explicitly.
@pvretano You confirm the interpretation?

I believe the base64 is used as alias of binary by default (i.e.: when "contentEncoding": "base64" is not explicitly indicated) because a "string"+"binary" is in itself ambiguous (is it octal, hexadecimal, bits, spaced groups of bytes, etc.?).

[bpross-52n]

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