Schema defined as part of OpenAPIs should possess a description of the object in its entirety. Let each property description tell more about the parts of an object and work to describe object in relationship to standards, other related objects, and what it will do as a whole as part of the request or the response that it is being used in.
Schema descriptions shouldn’t be longer than a paragraph and tell the narrative of the object, leaving properties, examples, and other elements to tell the full story. Keep your schema descriptions simple, plain language, and informative, helping make it something that provides a quick read for API consumers putting the object to work in their applications.