Update docs for v1

docs/2-implementing.md

@@ -6,7 +6,7 @@ permalink: /implementing/
 
 # Implementing JsonSchema
 
-[Deriving `JsonSchema`]({{ site.baseurl }}{% link 1-deriving.md %}) is usually the easiest way to enable JSON schema generation for your types. But if you need more customisation, you can also implement `JsonSchema` manually. This trait has two associated functions which must be implemented, and one which can optionally be implemented:
+[Deriving `JsonSchema`]({{ site.baseurl }}{% link 1-deriving.md %}) is usually the easiest way to enable JSON schema generation for your types. But if you need more customisation, you can also implement `JsonSchema` manually. This trait has two associated functions which must be implemented, one which usually _should_ be implemented, and one which can optionally be implemented:
 
 ## schema_name
 
@@ -14,9 +14,9 @@ permalink: /implementing/
 fn schema_name() -> Cow<'static, str>;
 ```
 
-This function returns the human-readable friendly name of the type's schema, which frequently is just the name of the type itself. The schema name is used as the title for root schemas, and the key within the root's `definitions` property for subschemas.
+This function returns the human-readable friendly name of the type's schema, which frequently is just the name of the type itself. The schema name is used as the title for root schemas, and the key within the root's `$defs` property for subschemas.
 
-## schema_id
+## schema_id (optional but recommended)
 
 ```rust
 fn schema_id() -> Cow<'static, str>;
@@ -47,18 +47,23 @@ impl JsonSchema for NonGenericType {
     }
 
     fn json_schema(_gen: &mut SchemaGenerator) -> Schema {
-        todo!()
+        json_schema!({
+            "type": "object",
+            "foo": "bar"
+        })
     }
 }
 ```
 
+The default implementation of this function returns `Self::schema_name()`.
+
 ## json_schema
 
 ```rust
 fn json_schema(gen: &mut gen::SchemaGenerator) -> Schema;
 ```
 
-This function creates the JSON schema itself. The `gen` argument can be used to check the schema generation settings, or to get schemas for other types. If you do need schemas for other types, you should call the `gen.subschema_for::<T>()` method instead of `<T>::json_schema(gen)`, as `subschema_for` can add `T`'s schema to the root schema's `definitions` so that it does not need to be duplicated when used more than once.
+This function creates the JSON schema itself. The `gen` argument can be used to check the schema generation settings, or to get schemas for other types. If you do need schemas for other types, you should call the `gen.subschema_for::<T>()` method instead of `<T>::json_schema(gen)`, as `subschema_for` can add `T`'s schema to the root schema's `$defs` so that it does not need to be duplicated when used more than once.
 
 `json_schema` should not return a `$ref` schema.
 
@@ -68,7 +73,7 @@ This function creates the JSON schema itself. The `gen` argument can be used to
 fn always_inline_schema() -> bool;
 ```
 
-If this function returns `false`, then Schemars can re-use the generate schema where possible by adding it to the root schema's `definitions` and having other schemas reference it using the `$ref` keyword. This can greatly simplify schemas that include a particular type multiple times, especially if that type's schema is fairly complex.
+If this function returns `false`, then Schemars can re-use the generate schema where possible by adding it to the root schema's `$defs` and having other schemas reference it using the `$ref` keyword. This can greatly simplify schemas that include a particular type multiple times, especially if that type's schema is fairly complex.
 
 Generally, this should return `true` for types with simple schemas (such as primitives). For more complex types, it should return `false`. For recursive types, this **must** return `false` to prevent infinite cycles when generating schemas.