ListUsers: wildcards, excluded users and minor fixes

docs/content/concepts.mdx

@@ -606,7 +606,7 @@ A **list users request** is a call to the <ProductName format={ProductNameFormat
 
 List users requests are completed using the relevant `ListUsers` method in SDKs, the `fga query list-users` command in the CLI, or by manually calling the [ListUsers endpoint](/api/service#Relationship%20Queries/ListUsers) using curl or in your code.
 
-The list users endpoint responds with a list of users and excluded users for a given type that have the specificed relationship with an object.
+The list users endpoint responds with a list of users for a given type that have the specificed relationship with an object.
 
 For example, the following returns all the users of type `user` that have the `viewer` relationship for `document:planning`:
 
@@ -617,8 +617,11 @@ For example, the following returns all the users of type `user` that have the `v
   relation="viewer"
   userFilterType="user"
   expectedResults={{
-    users: [{ object: { type: "user:anne" } }],
-    excluded_users: [{ object: { type: "user:beth" } }]
+    users: [
+      { object: { type: "user", id: "anne" }}, 
+      { object: { type: "user", id: "beth" }}
+    ],
+    excluded_users: []
   }}
 />
 

docs/content/getting-started/perform-list-users.mdx

@@ -61,7 +61,7 @@ This section will illustrate how to perform a <ProductConcept section="what-is-a
 
 </TabItem>
 
-{/* <TabItem value={SupportedLanguage.PYTHON_SDK} label={languageLabelMap.get(SupportedLanguage.PYTHON_SDK)}>
+{ /* <TabItem value={SupportedLanguage.PYTHON_SDK} label={languageLabelMap.get(SupportedLanguage.PYTHON_SDK)}>
 
 1. <SdkSetupPrerequisite />
 2. You have [installed the SDK](./install-sdk.mdx).
@@ -155,7 +155,7 @@ To return all users of type `user` that have have the `reader` relationship with
   relation="reader"
   userFilterType="user"
   expectedResults={{
-    users: [{ object: { type: "user:anne" } }, { object: { type: "user:beth" } }],
+    users: [{ object: { type: "user", id: "anne" } }, { object: { type: "user", id: "beth" } }],
     excluded_users: []
   }}
   skipSetup={true}
@@ -175,6 +175,81 @@ The result `user:anne` and `user:beth` are the `user` objects that have the `rea
 The performance characteristics of the ListUsers endpoint vary drastically depending on the model complexity, number of tuples, and the relations it needs to evaluate. Relations with 'and' or 'but not' are particularly expensive to evaluate.
 :::
 
+## Type-bound Public Access
+
+The list users API supports tuples expressing public access via the wildcard syntax (e.g. `user:*`). Wildcard tuples that satisfy the query criteria will be returned with the `wildcard` root object property that will specify the type. The API will not expand wildcard results further to any ID'd subjects. Further, specific users that have been granted accesss will be returned in addition to any public acccess for that user's type.
+
+Example response with type-bound public access:
+
+```json
+{
+  "users": [
+    {
+      "wildcard": {
+        "type":"user"
+      }
+    },
+    {
+      "object": {
+        "type":"user",
+        "id":"anne"
+      }
+    }
+  ],
+  "excluded_users":[]
+}
+
+```
+
+## Excluded Users
+
+In certain cases, it is important to communicate that certain users are excluded from returned usersets and do not have a relation to the target obect. Most notably, this occurs in models with type-bound public access via wildcard syntax (e.g. `user:*`) and negation via the `but not` syntax. 
+
+Below is an example where excluded users are returned:
+
+```dsl.openfga
+model
+  schema 1.1
+
+type user
+
+type document
+  relations
+    define viewer: [user:*] but not blocked
+    define blocked: [user]
+```
+
+With the tuples:
+
+| user | relation| object|
+|------|---------|-------|
+| user:* | viewer| document:1|
+| user:anne | blocked| document:1|
+
+And ultimately calling the List Users API for `document:1` with relation `viewer` of type `user`:
+
+<ListUsersRequestViewer
+  authorizationModelId="01HVMMBCMGZNT3SED4Z17ECXCA"
+  objectType="document"
+  objectId="1"
+  relation="viewer"
+  userFilterType="user"
+  expectedResults={{
+    users: [{ wildcard: { type: "user" } }],
+    excluded_users: [{ object: { type: "user", id: "anne" } }]
+  }}
+  skipSetup={true}
+  allowedLanguages={[
+    SupportedLanguage.JS_SDK,
+    SupportedLanguage.GO_SDK,
+    SupportedLanguage.DOTNET_SDK,
+    SupportedLanguage.JAVA_SDK,
+    SupportedLanguage.CLI,
+    SupportedLanguage.CURL,
+  ]}
+/>
+
+
 ## Related Sections
 
 <RelatedSection