Should this be:
"MUST be of a Schema Object or Schema Reference" ? (Ditto on the other items in the list.

Please elaborate on what "not a standard JSON Schema." means. However, if it means "not a full JSON Schema but the OpenAPI Specification schema", I think we should just drop this since you already refer explicitly to [Schema Object](#schemaObject)

It should be the Schema Object, not Schema Reference (which I assume you meant JSON Reference). The Schema Object contains the JSON Reference in it.

The 'standard JSON Schema' is in reference to the initial point that the Schema Object is an extended subset of JSON Schema. I'd rather keep this explicit here due to questions raised in the past.

@DavidBiesack I almost responded with a "+1" to your comment but I think the "Inline or referenced schema" as to being either a Schema Object or a JSON Reference to a Schema Object defined elsewhere. @webron's wording seem fine to me.

I still think "not a standard JSON Schema" may be confusing and not needed -- it just raises questions and distracts from the spec. Better IMHO would be to remove it or as @whitlockjc suggests, add "or a or a JSON Reference to a Schema Object" (I don't thing "defined elsewhere" is needed; that is implicit in being a JSON References - concise is better)

I think it is useful to remind people that even when embedding schema objects in allOf what is being embedded is not a regular JSON Schema. I suspect many people don't realize that the schemas inside OpenAPI are not regular JSON Schemas.

Doesn't linking to a Schema Object do this?

typo: "of the type" s/b "if the type"

suggest change "As a Reference Object" to "A Reference Object"

remove parens here (not used elsewhere in OAS when describing CommonMark)

remove parens here (not used elsewhere in OAS when describing CommonMark)

Please add an example:

Below are examples showing an array of Pet objects using petType as a discriminator:

- name: "Fluffy"
  petType: "Cat"
  huntingSkill: "lazy"
- name: "Rover"
  petType: "Dog"
  packSize: 6

[
  {
    "name" : "Fluffy",
    "petType" : "Cat",
    "huntingSkill" : "lazy"
  },
  {
    "name" : "Rover",
    "petType" : "Dog",
    "packSize" : 6
  }
]

Does it read better using "JSON-Schema Draft Wright 00" here since that is what you mentioned prior? Also, was hyphenating JSON Schema to JSON-Schema intentional in the link text? If so, what's the rules behind when we hyphenate and when we do not?

The hyphen is a mistake. Will fix.

I can change it to JSON Schema Draft Wright 00 everywhere, but it's not the exact name. The exact name is draft-wright-json-schema-00 which is awkward to write across the doc.

Makes sense. I trust your judgement.

Fixed.

I'm not sure I understand what's being said here. Is the Reference Object only for local references, as in references within the same document? If that's the case, the value is itself a JSON Pointer as a JSON Reference allows both local and remote references.

Reference Object is for all references whether local or remote.

That's what I was hoping for. So in that case, the "that uses a JSON Pointer as its value" is not accurate is it? The JSON Pointer version of a $ref value is for local only and since a Reference Object is for local and remote references, isn't the Reference Object's $ref just a URI per the JSON References spec.

You're right, @whitlockjc. The indication of JSON Pointer here is not needed. It was added in 2.0, back in the days where things were still unclear to us all. We now know better - A JSON References, is a JSON Reference, and in some cases the value is a JSON Pointer. The actual explanation here is wrong and unneeded. Will remove.

👍

Completely reworked JSON Reference, see main comment.

Can it be a JSON Reference to a Schema Object? If so, you might want to use similar wording like you did elsewhere.

To me, any place you could have a Schema Object you would allow a JSON Reference to a Schema Object but it is an either/or, as in you cannot mix a JSON Reference and a Schema Object in the same object. I think we could have some extra wording here making sure this is known to be the case, much like we document the items property as being applicable and required only when type: array.

How about defining a section for OpenAPI Schema Definition and cite that in all these places where an inline or ref is allowed, and then define OpenAPI Schema Definition as exactly one of (inline) Schema Object or a JSON reference to a Schema Object

You don't specifically tell what the type is, or its purpose. Would it make sense to do this and then throw the existing content into a "(Note: ...)"?

Without an example, this portion is unclear to me.

Actually, I might get this. Are you saying that the value of the discriminator field must match the name of a definition? Does this mean you can only use values that match keys of #/components/definitions?

Good point -- we rely heavily on external schema files via $ref. For example, if Cat and Dog are defined externally, I should still be able to use them. However for a schema included from an external schema.json there is no name as there is for one defined in /components/definitions. If all three schema (Pet, Cat, Doc) were defined externally (so that they can be used in multiple OpenAPI documents) and there is no single /components/definitions in which they reside, how would this work?

We'll be handling the discriminator in a separate PR.

I still think "not a standard JSON Schema" may be confusing and not needed -- it just raises questions and distracts from the spec. Better IMHO would be to remove it or as @whitlockjc suggests, add "or a or a JSON Reference to a Schema Object" (I don't thing "defined elsewhere" is needed; that is implicit in being a JSON References - concise is better)

How about defining a section for OpenAPI Schema Definition and cite that in all these places where an inline or ref is allowed, and then define OpenAPI Schema Definition as exactly one of (inline) Schema Object or a JSON reference to a Schema Object

I'm not sure what this means. Override which property - the discriminator field (petType in this example)? If so, how is it overridden and specified? Would I do:

  Cat:  ## "Cat" will be used as the discriminator value
    description: A representation of a cat
    allOf:
    - $ref: '#/definitions/Pet'
    - type: object
      properties:
         petType:
              type: string
              enum:
              - Cat
          huntingSkill:
             ...

An example would help.

Good point -- we rely heavily on external schema files via $ref. For example, if Cat and Dog are defined externally, I should still be able to use them. However for a schema included from an external schema.json there is no name as there is for one defined in /components/definitions. If all three schema (Pet, Cat, Doc) were defined externally (so that they can be used in multiple OpenAPI documents) and there is no single /components/definitions in which they reside, how would this work?

Here you call it "JSON Schema Core" but you reference it earlier as "JSON Schema Specification Wright Draft 00". Make a decision and use it in both places.

JSON Schema is split into two specifications - Core and Validation. Can't keep it as one, and shouldn't reference both every single time.

Fair enough.

Should "in place" be "in its place"?

The third sentence doesn't make sense to me. What about mentioning the caveat about mixing other properties with $ref into the Reference Object documentation and omitting the last two sentences?