Description
AWS has some services where they accept an arbitrary JSON document (older services with such need were using a string property containing a JSON string, but this causes double JSON encoding when the main serialization is also JSON).
The metadata file represents that as a shape with no member and a document: true property: https://github.com/aws/aws-sdk-php/blob/33f6d393834053b11a5fc10573a211d92e61c2db/src/data/bedrock-runtime/2023-09-30/api-2.json#L970-L974
Looking at official AWS SDKs for other languages (the official PHP SDK does not returned typed responses and so cannot be used as comparison), here is how they represent it:
- JS represent it as a native JS value, with a type restricted to values that can be represented in JSON (which requires support for recursive type definitions, which we don't have in phpstan or psalm type aliases): https://github.com/smithy-lang/smithy-typescript/blob/8dec1794d4e0368417ba52ba0a05c5f08eb6348c/packages/types/src/shapes.ts#L14-L22
- the .NET SDK encapsulates this in a
Documentclass provided in their core package, with accessors to check the type of the value and read it in this type (with a hook in the JSON unmarshaller to decode it in a custom way): https://github.com/aws/aws-sdk-net/blob/09201e894db71b5d536db6cb0975f361b85f1f52/sdk/src/Core/Amazon.Runtime/Documents/Document.cs - The C++ SDK encapsulates it in Document and DocumentView objects in their core package, which are wrappers around their json object representation (the DocumentView is similar to the .NET API): https://github.com/aws/aws-sdk-cpp/blob/main/src/aws-cpp-sdk-core/include/aws/core/utils/Document.h
- The Java SDK uses a
Documentinterface in their core package, with internal implementations for each type of JSON values: https://github.com/aws/aws-sdk-java-v2/blob/033602390807ad60802b9752bb6518ab1e6102c6/core/sdk-core/src/main/java/software/amazon/awssdk/core/document/Document.java#L48. This SDK seems to use its own JSON representation (they have JsonNode) to handle the unmarshalled representation of JSON. - the Ruby SDK represents that as a native Ruby value (without describing the precise type of values inside the arrays or hashes as this would require a recursive type): https://github.com/aws/aws-sdk-ruby/blob/934a6ad172c65754fa0975b48464c5499f368bd3/gems/aws-sdk-bedrockruntime/lib/aws-sdk-bedrockruntime/types.rb#L690-L692
Based on that analysis and to be idiomatic to PHP, I suggest represent document shapes as a native PHP value and using bool|string|int|float|null|list<mixed>|array<string, mixed> as phpdoc type (bool|string|int|float|null|array as native type).