Repository: pydantic/pydantic
Pull request: updating docs with more SkipJsonSchema info
## Change Summary

Update docs info, specifically re json schema tools.

## Related issue number

Closes #8160

## Checklist

* [x] The pull request title is a good summary of the changes - it will be used in the changelog
* [ ] Unit tests for the changes exist
* [x] Tests pass on CI
* [x] Documentation reflects the changes where applicable
* [x] My PR is ready to review, **please add a comment including the phrase "please review" to assign reviewers**


Selected Reviewer: @lig

Problem statement:
More things to document
I've been doing some in depth stuff with pydantic and discovered we don't have great documentation for:
* `WithJsonSchema` - needs to be talked about on the JSON Schema page, with an example, link to docs
* `__get_pydantic_json_schema__` - on same page, needs an example

Hints from issue discussion:
Will do today. Also going to add better docs / examples for `SkipJsonSchema`
Unless I'm mistaken, I haven't found any reference to `computed_field` in concepts (apart from a note in [Serialization](https://docs.pydantic.dev/latest/concepts/serialization/)). It might be beneficial to have a dedicated section? What do you think?
@Viicos,

Good call - probably makes sense to have a section in the `Fields` concepts section. I can add that as well 😄
Also `json_schema_extra` with a callable 😄
Taking a closer look at the JSON schema page now. I think it could help to do a bit of a conceptual overview / rewrite that touches on all of the various ways to modify schema, and the use cases for each. Will include that in this PR.

Commit message: Wording fix

Co-authored-by: psychedelicious <4822129+psychedelicious@users.noreply.github.com>

Patch to review:
diff --git a/docs/concepts/fields.md b/docs/concepts/fields.md
index 448902640b2..56a74c22e36 100644
--- a/docs/concepts/fields.md
+++ b/docs/concepts/fields.md
@@ -41,6 +41,7 @@ class User(BaseModel):
 ## Using `Annotated`
 
 The `Field` function can also be used together with `Annotated`.
+For versions of Python prior to 3.9, `typing_extensions.Annotated` can be used.
 
 ```py
 from uuid import uuid4
@@ -54,6 +55,11 @@ class User(BaseModel):
     id: Annotated[str, Field(default_factory=lambda: uuid4().hex)]
 ```
 
+!!! note
+    Defaults can be set outside `Annotated` as the assigned value or with `Field.default_factory` inside `Annotated`.
+    The `Field.default` argument is not supported inside `Annotated`.
+
+
 ## Field aliases
 
 For validation and serialization, you can define an alias for a field.
@@ -761,7 +767,7 @@ See the [Serialization] section for more details.
 
 ## Customizing JSON Schema
 
-There are fields that exclusively to customise the generated JSON Schema:
+Some fields are exclusively used to customise the generated JSON Schema:
 
 * `title`: The title of the field.
 * `description`: The description of the field.
@@ -819,6 +825,38 @@ print(User.model_json_schema())
 """
 ```
 
+Read more about JSON schema customization / modification in the [Customizing JSON Schema] section of the JSON schema docs.
+
+## The `computed_field` decorator
+
+??? api "API Documentation"
+    [`pydantic.fields.computed_field`][pydantic.fields.computed_field]<br>
+
+The `computed_field` decorator can be used to include `property` or `cached_property` attributes when serializing a
+model or dataclass. This can be useful for fields that are computed from other fields, or for fields that
+are expensive to computed (and thus, are cached).
+
+Here's an example:
+
+```py
+from pydantic import BaseModel, computed_field
+
+
+class Box(BaseModel):
+    width: float
+    height: float
+    depth: float
+
+    @computed_field
+    def volume(self) -> float:
+        return self.width * self.height * self.depth
+
+
+b = Box(width=1, height=2, depth=3)
+print(b.model_dump())
+#> {'width': 1.0, 'height': 2.0, 'depth': 3.0, 'volume': 6.0}
+```
+
 
 [JSON Schema Draft 2020-12]: https://json-schema.org/understanding-json-schema/reference/numeric.html#numeric-types
 [Discriminated Unions]: ../api/standard_library_types.md#discriminated-unions-aka-tagged-unions
@@ -828,3 +866,4 @@ print(User.model_json_schema())
 [frozen dataclass documentation]: https://docs.python.org/3/library/dataclasses.html#frozen-instances
 [Validate Assignment]: models.md#validate-assignment
 [Serialization]: serialization.md#model-and-field-level-include-and-exclude
+[Customizing JSON Schema]: json_schema.md#customizing-json-schema
diff --git a/docs/concepts/json_schema.md b/docs/concepts/json_schema.md
index 919b2e2e9d0..e355827edb5 100644
--- a/docs/concepts/json_schema.md
+++ b/docs/concepts/json_schema.md
@@ -1,22 +1,44 @@
 ??? api "API Documentation"
     [`pydantic.json_schema`][pydantic.json_schema]<br>
 
-Pydantic allows automatic creation of JSON schemas from models.
-
-Using Pydantic, there are several ways to generate JSON schemas or JSON representations from fields or models:
-
-* [`BaseModel.model_json_schema`][pydantic.main.BaseModel.model_json_schema] returns a jsonable dict of the schema.
-* [`BaseModel.model_dump_json`][pydantic.main.BaseModel.model_dump_json] returns a JSON string representation of the
-    dict of the schema.
-* [`TypeAdapter.dump_json`][pydantic.type_adapter.TypeAdapter.dump_json] serializes an instance of the adapted type to
-    JSON.
-* [`TypeAdapter.json_schema`][pydantic.type_adapter.TypeAdapter.json_schema] generates a JSON schema for the adapted type.
-
+Pydantic allows automatic creation and customization of JSON schemas from models.
 The generated JSON schemas are compliant with the following specifications:
 
 * [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12/release-notes.html)
 * [OpenAPI extensions](https://github.com/OAI/OpenAPI-Specification).
 
+## Generating JSON Schema
+
+Use the following functions to generate JSON schema:
+
+* [`BaseModel.model_json_schema`][pydantic.main.BaseModel.model_json_schema] - returns a jsonable dict of a model's schema
+* [`TypeAdapter.json_schema`][pydantic.type_adapter.TypeAdapter.json_schema] - returns a jsonable dict of an adapted type's schema
+
+!!! note
+    These methods are not to be confused with [`BaseModel.model_dump_json`][pydantic.main.BaseModel.model_dump_json]
+    and [`TypeAdapter.dump_json`][pydantic.type_adapter.TypeAdapter.dump_json], which serialize instances of the
+    model or adapted type, respectively. These methods return JSON strings.
+
+!!! note "on the "jsonable" nature of JSON schema"
+    Regarding the "jsonable" nature of the [`model_json_schema`][pydantic.main.BaseModel.model_json_schema] results,
+    calling `json.dumps(m.model_json_schema())`on some `BaseModel` `m` returns a valid JSON string. Similarly, for
+    [`TypeAdapter.json_schema`][pydantic.type_adapter.TypeAdapter.json_schema], calling
+    `json.dumps(ta.json_schema())`on some `TypeAdapter` `ta` returns a valid JSON string.
+
+
+!!! tip
+    Pydantic offers support for both of:
+
+    1. [Customizing JSON Schema](#customizing-json-schema)
+    2. [Customizing the JSON Schema Generation Process](#customizing-the-json-schema-generation-process)
+
+    The first approach generally has a more narrow scope, allowing for customization of the JSON schema for
+    more specific cases and types. The second approach generally has a more broad scope, allowing for customization
+    of the JSON schema generation process overall. The same effects can be achieved with either approach, but
+    depending on your use case, one approach might offer a more simple solution than the other.
+
+Here's an example of generating JSON schema from a `BaseModel`:
+
 ```py output="json"
 import json
 from enum import Enum
@@ -58,7 +80,8 @@ class MainModel(BaseModel):
     )
 
 
-print(json.dumps(MainModel.model_json_schema(), indent=2))
+main_model_schema = MainModel.model_json_schema()  # (1)!
+print(json.dumps(main_model_schema, indent=2))  # (2)!
 """
 {
   "$defs": {
@@ -132,35 +155,15 @@ print(json.dumps(MainModel.model_json_schema(), indent=2))
 """
 ```
 
-## General notes on JSON schema generation
-
-* The JSON schema for `Optional` fields indicates that the value `null` is allowed.
-* The `Decimal` type is exposed in JSON schema (and serialized) as a string.
-* The JSON schema does not preserve `namedtuple`s as `namedtuple`s.
-* When they differ, you can specify whether you want the JSON schema to represent the inputs to validation
-    or the outputs from serialization.
-* Sub-models used are added to the `$defs` JSON attribute and referenced, as per the spec.
-* Sub-models with modifications (via the `Field` class) like a custom title, description, or default value,
-    are recursively included instead of referenced.
-* The `description` for models is taken from either the docstring of the class or the argument `description` to
-    the `Field` class.
-* The schema is generated by default using aliases as keys, but it can be generated using model
-    property names instead by calling [`model_json_schema()`][pydantic.main.BaseModel.model_json_schema] or
-    [`model_dump_json()`][pydantic.main.BaseModel.model_dump_json] with the `by_alias=False` keyword argument.
-* The format of `$ref`s can be altered by calling [`model_json_schema()`][pydantic.main.BaseModel.model_json_schema]
-    or `model_dump_json()`][pydantic.main.BaseModel.model_dump_json] with the `ref_template` keyword argument.
-
-!!! note
-    Regarding the "jsonable" nature of the [`model_json_schema`][pydantic.main.BaseModel.model_json_schema] results,
-    calling `json.dumps(m.model_json_schema())`on some `BaseModel` `m` returns a valid JSON string.
-
-
-## Getting schema of a specified type
+1. This produces a "jsonable" dict of `MainModel`'s schema.
+2. Calling `json.dumps` on the schema dict produces a JSON string.
 
 The [`TypeAdapter`][pydantic.type_adapter.TypeAdapter] class lets you create an object with methods for validating, serializing,
 and producing JSON schemas for arbitrary types. This serves as a complete replacement for `schema_of` in
 Pydantic V1 (which is now deprecated).
 
+Here's an example of generating JSON schema from a `TypeAdapter`:
+
 ```python
 from typing import List
 
@@ -171,7 +174,95 @@ print(adapter.json_schema())
 #> {'items': {'type': 'integer'}, 'type': 'array'}
 ```
 
-## Field customization
+You can also generate JSON schemas for combinations of `BaseModel`s and `TypeAdapter`s, as shown in this example:
+
+```py output="json"
+import json
+from typing import Union
+
+from pydantic import BaseModel, TypeAdapter
+
+
+class Cat(BaseModel):
+    name: str
+    color: str
+
+
+class Dog(BaseModel):
+    name: str
+    breed: str
+
+
+ta = TypeAdapter(Union[Cat, Dog])
+ta_schema = ta.json_schema()
+print(json.dumps(ta_schema, indent=2))
+"""
+{
+  "$defs": {
+    "Cat": {
+      "properties": {
+        "name": {
+          "title": "Name",
+          "type": "string"
+        },
+        "color": {
+          "title": "Color",
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "color"
+      ],
+      "title": "Cat",
+      "type": "object"
+    },
+    "Dog": {
+      "properties": {
+        "name": {
+          "title": "Name",
+          "type": "string"
+        },
+        "breed": {
+          "title": "Breed",
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "breed"
+      ],
+      "title": "Dog",
+      "type": "object"
+    }
+  },
+  "anyOf": [
+    {
+      "$ref": "#/$defs/Cat"
+    },
+    {
+      "$ref": "#/$defs/Dog"
+    }
+  ]
+}
+"""
+```
+
+## Customizing JSON Schema
+
+The generated JSON schema can be customized at both the model level via:
+
+1. [Field-level customization](#field-level-customization) with the [`Field`][pydantic.fields.Field] constructor
+2. [Model-level customization](#model-level-customization) with [`model_config`][pydantic.config.ConfigDict]
+
+For custom types, Pydantic offers other tools for customizing JSON schema generation:
+
+1. [Implementing `__get_pydantic_core_schema__`](#implementing-getpydanticcoreschema)
+2. [Implementing `__get_pydantic_json_schema__`](#implementing-getpydanticjsonschema)
+2. [`WithJsonSchema` annotation](#withjsonschema-annotation)
+3. [`SkipJsonSchema` annotation](#skipjsonschema-annotation)
+
+### Field-Level Customization
 
 Optionally, the [`Field`][pydantic.fields.Field] function can be used to provide extra information about the field
 and validations.
@@ -179,17 +270,7 @@ and validations.
 See [Customizing JSON Schema](fields.md#customizing-json-schema) for details on field parameters that are used
 exclusively to customize the generated JSON schema.
 
-You can also use [model config][pydantic.config.ConfigDict] to customize JSON serialization and extra schema properties on a model.
-Specifically, the following config options are relevant:
-
-* [`title`][pydantic.config.ConfigDict.title]
-* [`use_enum_values`][pydantic.config.ConfigDict.use_enum_values]
-* [`json_schema_extra`][pydantic.config.ConfigDict.json_schema_extra]
-* [`ser_json_timedelta`][pydantic.config.ConfigDict.ser_json_timedelta]
-* [`ser_json_bytes`][pydantic.config.ConfigDict.ser_json_bytes]
-* [`ser_json_inf_nan`][pydantic.config.ConfigDict.ser_json_inf_nan]
-
-### Unenforced `Field` constraints
+#### Unenforced `Field` constraints
 
 If Pydantic finds constraints which are not being enforced, an error will be raised. If you want to force the
 constraint to appear in the schema, even though it's not being checked upon parsing, you can use variadic arguments
@@ -235,9 +316,7 @@ print(ModelB.model_json_schema())
 """
 ```
 
-### typing.Annotated Fields
-
-Rather than assigning a `Field` value, it can be specified in the type hint with `typing.Annotated`:
+You can specify JSON schema modifications via the `Field` constructor via `typing.Annotated` as well:
 
 ```py
 from uuid import uuid4
@@ -270,13 +349,17 @@ print(Foo.model_json_schema())
 """
 ```
 
-!!! note
-    Defaults can be set outside `Annotated` as the assigned value or with `Field.default_factory` inside `Annotated`.
-    The `Field.default` argument is not supported inside `Annotated`.
+### Model-Level Customization
 
-For versions of Python prior to 3.9, `typing_extensions.Annotated` can be used.
+You can also use [model config][pydantic.config.ConfigDict] to customize JSON schema generation on a model.
+Specifically, the following config options are relevant:
+
+* [`title`][pydantic.config.ConfigDict.title]
+* [`json_schema_extra`][pydantic.config.ConfigDict.json_schema_extra]
+* [`schema_generator`][pydantic.config.ConfigDict.schema_generator]
+* [`json_schema_mode_override`][pydantic.config.ConfigDict.json_schema_mode_override]
 
-## Modifying the schema
+### Implementing `__get_pydantic_core_schema__`
 
 Custom types (used as `field_name: TheType` or `field_name: Annotated[TheType, ...]`) as well as `Annotated` metadata
 (used as `field_name: Annotated[int, SomeMetadata]`)
@@ -473,6 +556,75 @@ except ValidationError as e:
     """
 ```
 
+!!! tip
+    Note that you *must* return a schema, even if you are just mutating it in place.
+
+
+### Implementing `__get_pydantic_json_schema__`
+
+You can also implement `__get_pydantic_json_schema__` to modify or override the generated json schema.
+Modifying this method only affects the JSON schema - it doesn't effect the core schema, which is used for validation and serialization.
+
+Here's an example of modifying the generated JSON schema:
+
+
+```py output="json"
+import json
+
+from pydantic_core import CoreSchema
+
+from pydantic import BaseModel, GetJsonSchemaHandler
+from pydantic.json_schema import JsonSchemaValue
+
+
+class Person(BaseModel):
+    name: str
+    age: int
+
+    @classmethod
+    def __get_pydantic_json_schema__(
+        cls, core_schema: CoreSchema, handler: GetJsonSchemaHandler
+    ) -> JsonSchemaValue:
+        json_schema = handler(core_schema)
+        json_schema = handler.resolve_ref_schema(json_schema)
+        json_schema['examples'] = [
+            {
+                'name': 'John Doe',
+                'age': 25,
+            }
+        ]
+        return json_schema
+
+
+print(json.dumps(Person.model_json_schema(), indent=2))
+"""
+{
+  "examples": [
+    {
+      "age": 25,
+      "name": "John Doe"
+    }
+  ],
+  "properties": {
+    "name": {
+      "title": "Name",
+      "type": "string"
+    },
+    "age": {
+      "title": "Age",
+      "type": "integer"
+    }
+  },
+  "required": [
+    "name",
+    "age"
+  ],
+  "title": "Person",
+  "type": "object"
+}
+"""
+```
+
 To override the schema completely, do not call the handler and return your own
 `CoreSchema`:
 
@@ -572,6 +724,61 @@ print(m.model_fields)
 """
 ```
 
+### `WithJsonSchema` annotation
+
+??? api "API Documentation"
+    [`pydantic.json_schema.WithJsonSchema`][pydantic.json_schema.WithJsonSchema]<br>
+
+The `WithJsonSchema` annotation can be used to override the generated (baes) JSON schema for a given type without
+the need to implement `__get_pydantic_core_schema__` on the type itself.
+
+This provides a way to set a JSON schema for types that would otherwise raise errors when producing a JSON schema,
+such as `Callable`, or types that have an `is-instance` core schema.
+
+For example, the use of a `PlainValidator` in the following example would otherwise raise an error
+when producing a JSON schema because the `PlainValidator` is a `Callable`. However, by using the `WithJsonSchema`
+annotation, we can override the generated JSON schema for the custom `MyInt` type:
+
+```py
+from typing_extensions import Annotated
+
+from pydantic import BaseModel, PlainValidator, WithJsonSchema
+
+MyInt = Annotated[
+    int, PlainValidator(lambda v: int(v) + 1), WithJsonSchema({'type': 'int'})
+]
+
+
+class Model(BaseModel):
+    a: MyInt
+
+
+print(Model(a='1').a)
+#> 2
+
+print(Model(a='1').model_json_schema())
+"""
+{
+    'properties': {'a': {'title': 'A', 'type': 'int'}},
+    'required': ['a'],
+    'title': 'Model',
+    'type': 'object',
+}
+"""
+```
+
+In the future, it's likely that Pydantic will add builtin support for JSON schema generation for types like `PlainValidator`,
+but the `WithJsonSchema` annotation will still be useful for other custom types.
+
+### `SkipJsonSchema` annotation
+
+??? api "API Documentation"
+    [`pydantic.json_schema.SkipJsonSchema`][pydantic.json_schema.SkipJsonSchema]<br>
+
+The `SkipJsonSchema` annotation can be used to skip a including field (or part of a field's specifications)
+from the generated JSON schema. See the API docs for more details.
+
+
 ## JSON schema types
 
 Types, custom field types, and constraints (like `max_length`) are mapped to the corresponding spec formats in the
@@ -586,6 +793,7 @@ The field schema mapping from Python or Pydantic to JSON schema is done as follo
 
 {{ schema_mappings_table }}
 
+
 ## Top-level schema generation
 
 You can also generate a top-level JSON schema that only includes a list of models and related
@@ -659,132 +867,7 @@ print(json.dumps(top_level_schema, indent=2))
 """
 ```
 
-## Schema customization
-
-You can customize the generated `$ref` JSON location: the definitions are always stored under the key
-`$defs`, but a specified prefix can be used for the references.
-
-This is useful if you need to extend or modify the JSON schema default definitions location. For example, with OpenAPI:
-
-```py output="json"
-import json
-
-from pydantic import BaseModel
-from pydantic.type_adapter import TypeAdapter
-
-
-class Foo(BaseModel):
-    a: int
-
-
-class Model(BaseModel):
-    a: Foo
-
-
-adapter = TypeAdapter(Model)
-
-print(
-    json.dumps(
-        adapter.json_schema(ref_template='#/components/schemas/{model}'),
-        indent=2,
-    )
-)
-"""
-{
-  "$defs": {
-    "Foo": {
-      "properties": {
-        "a": {
-          "title": "A",
-          "type": "integer"
-        }
-      },
-      "required": [
-        "a"
-      ],
-      "title": "Foo",
-      "type": "object"
-    }
-  },
-  "properties": {
-    "a": {
-      "$ref": "#/components/schemas/Foo"
-    }
-  },
-  "required": [
-    "a"
-  ],
-  "title": "Model",
-  "type": "object"
-}
-"""
-```
-
-It's also possible to extend or override the generated JSON schema in a model by implementing
-`__get_pydantic_json_schema__` on your model.
-
-For example, you could add `examples` to the JSON schema:
-
-```py output="json"
-import json
-
-from pydantic_core import CoreSchema
-
-from pydantic import BaseModel, GetJsonSchemaHandler
-from pydantic.json_schema import JsonSchemaValue
-
-
-class Person(BaseModel):
-    name: str
-    age: int
-
-    @classmethod
-    def __get_pydantic_json_schema__(
-        cls, core_schema: CoreSchema, handler: GetJsonSchemaHandler
-    ) -> JsonSchemaValue:
-        json_schema = handler(core_schema)
-        json_schema = handler.resolve_ref_schema(json_schema)
-        json_schema['examples'] = [
-            {
-                'name': 'John Doe',
-                'age': 25,
-            }
-        ]
-        return json_schema
-
-
-print(json.dumps(Person.model_json_schema(), indent=2))
-"""
-{
-  "examples": [
-    {
-      "age": 25,
-      "name": "John Doe"
-    }
-  ],
-  "properties": {
-    "name": {
-      "title": "Name",
-      "type": "string"
-    },
-    "age": {
-      "title": "Age",
-      "type": "integer"
-    }
-  },
-  "required": [
-    "name",
-    "age"
-  ],
-  "title": "Person",
-  "type": "object"
-}
-"""
-```
-
-Note that you *must* return a schema, even if you are just mutating it in place.
-
-## Customizing the JSON schema generation process
+## Customizing the JSON Schema Generation Process
 
 ??? api "API Documentation"
     [`pydantic.json_schema`][pydantic.json_schema.GenerateJsonSchema]<br>
@@ -870,3 +953,81 @@ print(validation_schema)
 }
 """
 ```
+
+## Customizing the `$ref`s in JSON Schema
+
+The format of `$ref`s can be altered by calling [`model_json_schema()`][pydantic.main.BaseModel.model_json_schema]
+or `model_dump_json()`][pydantic.main.BaseModel.model_dump_json] with the `ref_template` keyword argument.
+The definitions are always stored under the key `$defs`, but a specified prefix can be used for the references.
+
+This is useful if you need to extend or modify the JSON schema default definitions location. For example, with OpenAPI:
+
+```py output="json"
+import json
+
+from pydantic import BaseModel
+from pydantic.type_adapter import TypeAdapter
+
+
+class Foo(BaseModel):
+    a: int
+
+
+class Model(BaseModel):
+    a: Foo
+
+
+adapter = TypeAdapter(Model)
+
+print(
+    json.dumps(
+        adapter.json_schema(ref_template='#/components/schemas/{model}'),
+        indent=2,
+    )
+)
+"""
+{
+  "$defs": {
+    "Foo": {
+      "properties": {
+        "a": {
+          "title": "A",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "a"
+      ],
+      "title": "Foo",
+      "type": "object"
+    }
+  },
+  "properties": {
+    "a": {
+      "$ref": "#/components/schemas/Foo"
+    }
+  },
+  "required": [
+    "a"
+  ],
+  "title": "Model",
+  "type": "object"
+}
+"""
+```
+
+## Miscellaneous Notes on JSON Schema Generation
+
+* The JSON schema for `Optional` fields indicates that the value `null` is allowed.
+* The `Decimal` type is exposed in JSON schema (and serialized) as a string.
+* The JSON schema does not preserve `namedtuple`s as `namedtuple`s.
+* When they differ, you can specify whether you want the JSON schema to represent the inputs to validation
+    or the outputs from serialization.
+* Sub-models used are added to the `$defs` JSON attribute and referenced, as per the spec.
+* Sub-models with modifications (via the `Field` class) like a custom title, description, or default value,
+    are recursively included instead of referenced.
+* The `description` for models is taken from either the docstring of the class or the argument `description` to
+    the `Field` class.
+* The schema is generated by default using aliases as keys, but it can be generated using model
+    property names instead by calling [`model_json_schema()`][pydantic.main.BaseModel.model_json_schema] or
+    [`model_dump_json()`][pydantic.main.BaseModel.model_dump_json] with the `by_alias=False` keyword argument.
diff --git a/pydantic/fields.py b/pydantic/fields.py
index c48e4c4c7d3..e13748bf45f 100644
--- a/pydantic/fields.py
+++ b/pydantic/fields.py
@@ -1019,7 +1019,9 @@ def computed_field(
     repr: bool | None = None,
     return_type: Any = PydanticUndefined,
 ) -> PropertyT | typing.Callable[[PropertyT], PropertyT]:
-    """Decorator to include `property` and `cached_property` when serializing models or dataclasses.
+    """Usage docs: https://docs.pydantic.dev/2.6/concepts/fields#the-computed_field-decorator
+
+    Decorator to include `property` and `cached_property` when serializing models or dataclasses.
 
     This is useful for fields that are computed from other fields, or for fields that are expensive to compute and should be cached.
 
diff --git a/pydantic/json_schema.py b/pydantic/json_schema.py
index 1b9b0d17d15..7839ed8cc71 100644
--- a/pydantic/json_schema.py
+++ b/pydantic/json_schema.py
@@ -2243,7 +2243,9 @@ def _sort_json_schema(value: JsonSchemaValue, parent_key: str | None = None) ->
 
 @dataclasses.dataclass(**_internal_dataclass.slots_true)
 class WithJsonSchema:
-    """Add this as an annotation on a field to override the (base) JSON schema that would be generated for that field.
+    """Usage docs: https://docs.pydantic.dev/2.6/concepts/json_schema/#withjsonschema-annotation
+
+    Add this as an annotation on a field to override the (base) JSON schema that would be generated for that field.
     This provides a way to set a JSON schema for types that would otherwise raise errors when producing a JSON schema,
     such as Callable, or types that have an is-instance core schema, without needing to go so far as creating a
     custom subclass of pydantic.json_schema.GenerateJsonSchema.
@@ -2330,20 +2332,53 @@ def _get_all_json_refs(item: Any) -> set[JsonRef]:
 
     @dataclasses.dataclass(**_internal_dataclass.slots_true)
     class SkipJsonSchema:
-        """Add this as an annotation on a field to skip generating a JSON schema for that field.
+        """Usage docs: https://docs.pydantic.dev/2.6/concepts/json_schema/#skipjsonschema-annotation
+
+        Add this as an annotation on a field to skip generating a JSON schema for that field.
 
         Example:
             ```py
+            from typing import Union
+
             from pydantic import BaseModel
             from pydantic.json_schema import SkipJsonSchema
 
-            class Model(BaseModel):
-                a: int | SkipJsonSchema[None] = None
+            from pprint import pprint
 
 
-            print(Model.model_json_schema())
-            #> {'properties': {'a': {'default': None, 'title': 'A', 'type': 'integer'}}, 'title': 'Model', 'type': 'object'}
+            class Model(BaseModel):
+                a: Union[int, None] = None  # (1)!
+                b: Union[int, SkipJsonSchema[None]] = None  # (2)!
+                c: SkipJsonSchema[Union[int, None]] = None  # (3)!
+
+
+            pprint(Model.model_json_schema())
+            '''
+            {
+                'properties': {
+                    'a': {
+                        'anyOf': [
+                            {'type': 'integer'},
+                            {'type': 'null'}
+                        ],
+                        'default': None,
+                        'title': 'A'
+                    },
+                    'b': {
+                        'default': None,
+                        'title': 'B',
+                        'type': 'integer'
+                    }
+                },
+                'title': 'Model',
+                'type': 'object'
+            }
+            '''
             ```
+
+            1. The integer and null types are both included in the schema for `a`.
+            2. The integer type is the only type included in the schema for `b`.
+            3. The entirety of the `c` field is omitted from the schema.
         """
 
         def __class_getitem__(cls, item: AnyType) -> AnyType:


Code review comments:
diff_hunk: @@ -1,22 +1,44 @@
 ??? api "API Documentation"
     [`pydantic.json_schema`][pydantic.json_schema]<br>
 
-Pydantic allows automatic creation of JSON schemas from models.
-
-Using Pydantic, there are several ways to generate JSON schemas or JSON representations from fields or models:
-
-* [`BaseModel.model_json_schema`][pydantic.main.BaseModel.model_json_schema] returns a jsonable dict of the schema.
-* [`BaseModel.model_dump_json`][pydantic.main.BaseModel.model_dump_json] returns a JSON string representation of the
-    dict of the schema.
-* [`TypeAdapter.dump_json`][pydantic.type_adapter.TypeAdapter.dump_json] serializes an instance of the adapted type to
-    JSON.
-* [`TypeAdapter.json_schema`][pydantic.type_adapter.TypeAdapter.json_schema] generates a JSON schema for the adapted type.
-
+Pydantic allows automatic creation and customization of JSON schemas from models.
 The generated JSON schemas are compliant with the following specifications:
 
 * [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12/release-notes.html)
 * [OpenAPI extensions](https://github.com/OAI/OpenAPI-Specification).
 
+## Generating JSON Schema
+
+Use the following functions to generate JSON schema:
+
+* [`BaseModel.model_json_schema`][pydantic.main.BaseModel.model_json_schema] - returns a jsonable dict of a model's schema
+* [`TypeAdapter.json_schema`][pydantic.type_adapter.TypeAdapter.json_schema] - returns a jsonable dict of an adapted type's schema
+
+!!! note
+    These methods are not to be confused with [`BaseModel.model_dump_json`][pydantic.main.BaseModel.model_dump_json]
+    and [`TypeAdapter.dump_json`][pydantic.type_adapter.TypeAdapter.dump_json], which serialize instances of the
+    model or adapted type, respectively. These methods return JSON strings.
+
+!!! note "on the "jsonable" nature of JSON schema"
path: docs/concepts/json_schema.md
text: @user1:
How does this look? Cause the first double quotes is closed on the beginning of "jsonable".

@author:
Looks good, but good idea to check.