fix!: update Instance docs

openapi/components/paths/instances.yaml

@@ -16,7 +16,10 @@ paths:
       security:
         - apiKeyCookie: []
           authCookie: []
-      description: Returns an instance.
+      description: |-
+        Returns an instance. Please read [Instances Tutorial](https://vrchatapi.github.io/tutorials/instances/) for more information on Instances.
+
+        If an invalid instanceId is provided, this endpoint will simply return "null"!
       responses:
         '200':
           $ref: ../responses/instances/InstanceResponse.yaml
@@ -62,4 +65,4 @@ tags:
   $ref: ../tags.yaml
 components:
   securitySchemes:
-    $ref: ../securitySchemes.yaml
+    $ref: ../securitySchemes.yaml

openapi/components/schemas/Instance.yaml

@@ -1,82 +1,94 @@
-description: ''
+description: |-
+  * `hidden` field is only present if InstanceType is `hidden` aka "Friends+", and is instance creator.
+  * `friends` field is only present if InstanceType is `friends` aka "Friends", and is instance creator.
+  * `private` field is only present if InstanceType is `private` aka "Invite" or "Invite+", and is instance creator.
+title: Instance
+type: object
 properties:
   active:
     default: true
+    example: true
     type: boolean
   canRequestInvite:
     default: true
+    example: true
     type: boolean
   capacity:
+    type: integer
     example: 8
     minimum: 0
-    type: integer
   clientNumber:
-    minLength: 1
     type: string
+    minLength: 1
+    deprecated: true
+    description: Always returns "unknown".
   full:
     default: false
     type: boolean
   id:
     $ref: ./InstanceID.yaml
   instanceId:
-    minLength: 1
     type: string
-  location:
     minLength: 1
-    type: string
+    example: 12345~hidden(usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469)~region(eu)~nonce(27e8414a-59a0-4f3d-af1f-f27557eb49a2)
+  location:
+    $ref: ./InstanceID.yaml
   n_users:
-    minimum: 0
     type: integer
+    minimum: 0
+    example: 6
   name:
-    minLength: 1
     type: string
-  nonce:
     minLength: 1
-    type: string
+    example: '12345'
   ownerId:
     $ref: ./UserID.yaml
   permanent:
     default: false
     type: boolean
   photonRegion:
-    minLength: 1
-    type: string
+    $ref: ./Region.yaml
   platforms:
+    type: object
+    title: InstancePlatforms
+    additionalProperties: false
+    required:
+      - android
+      - standalonewindows
     properties:
       android:
         type: integer
+        minimum: 0
+        example: 1
       standalonewindows:
         type: integer
-    required:
-      - android
-      - standalonewindows
-    type: object
+        minimum: 0
+        example: 5
   region:
-    minLength: 1
-    type: string
+    $ref: ./Region.yaml
   shortName:
-    minLength: 1
     type: string
+    minLength: 1
+    example: fortran-grublink-41d83
   tags:
-    description: ' '
+    description: 'The tags array on Instances usually contain the language tags of the people in the instance. '
+    type: array
+    example:
+      - show_social_rank
+      - language_eng
+      - language_jpn
     items:
       $ref: ./Tag.yaml
-    type: array
   type:
-    minLength: 1
-    type: string
-  users:
-    deprecated: true
-    description: 'Always empty on non-existing instances, and non-present on existing instances.'
-    items:
-      type: object
-    type: array
-  world:
-    deprecated: true
-    description: 'Only present on non-existing instances, and only contains a very small subject of World object. Use World API instead.'
-    type: object
+    $ref: ./InstanceType.yaml
   worldId:
     $ref: ./WorldID.yaml
+  hidden:
+    $ref: ./UserID.yaml
+  friends:
+    $ref: ./UserID.yaml
+  private:
+    $ref: ./UserID.yaml
 required:
   - active
   - canRequestInvite
@@ -96,5 +108,3 @@ required:
   - tags
   - type
   - worldId
-title: Instance
-type: object

openapi/components/schemas/InstanceID.yaml

@@ -1,4 +1,5 @@
-example: wrld_ba913a96-fac4-4048-a062-9aa5db092812:123456
+type: string
+example: 'wrld_ba913a96-fac4-4048-a062-9aa5db092812:12345~hidden(usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469)~region(eu)~nonce(27e8414a-59a0-4f3d-af1f-f27557eb49a2)'
 pattern: '(wrld|wld)_[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}:(\d+)(~region\(([\w]+)\))?(~([\w]+)\(usr_([\w-]+)\)((\~canRequestInvite)?)(~region\(([\w].+)\))?~nonce\((.+)\))?'
 title: InstanceID
-type: string
+minLength: 41

openapi/components/schemas/InstanceType.yaml

@@ -0,0 +1,9 @@
+type: string
+title: InstanceType
+example: hidden
+enum:
+  - public
+  - hidden
+  - friends
+  - private
+description: ''

openapi/components/schemas/Region.yaml

@@ -0,0 +1,9 @@
+type: string
+title: Region
+default: us
+example: eu
+enum:
+  - us
+  - eu
+  - jp
+description: API/Photon region.