Add the capability to restrict properties on inherited object types via new proposed facet heritable

[araguacaima]

Even when an entity should be always the same, we do not always use it entirety in all use cases. A typical case of what I try to explain is the difference between the input and output of any endpoint with a POST method. For these, typically the "id" attribute of the entity is not provided at the POST input, but is usually returned at the output. For both, the entity should be the same, however it would be good to denote that the input for that POST call is forbidden to enter the "id". If we would like to use the same entity (with no duplication), how could we make an exception for the "id" attribute in the case of the input in a POST call?

My proposal is as follows: Adding some modifier that allows to "subtract", "restrict", "omit" or "not consider as an existing or valid" those attributes that belongs to the parent entity and not directly to the child. In other words, considerer that not all attributes of the parent are automatically inherited to the children. Thus, it is possible to define a child for the input of the "POST", and another for the output, but both inheriting from the same base entity, something like this:

entity.raml

#%RAML 1.0 Library

types:
  entity: # This is the base entity for both input and output post call
    type: object
    properties:
      entityId?:
        type: string
        description: Entity identifier.
      field?:
        type: boolean
        description: Field.

entity-child.raml

#%RAML 1.0 Library

uses:
  entity: entity.raml
  
types:
  post.in:  # This is the inherited entity which determines the specific structure for the input of the post call
    type: entity.entity
    properties:
      field:
  post.out:  # This is the inherited entity which determines the specific structure for the output of the post call
    type: entity.entity
    properties:
      entityId:
      field?:

The problem here is that, right now, by inheriting both the same base entity, all attributes of the parent entity are inherited to "entity.post.in" and "entity.post.out" children. Regardless of the fact that "entity.post.in" does not define the "entityId" attribute, it is absolutely valid because it is declared by the parent.

In order to reach the behavior mentioned above, I propose to add the facet "heritable" at "Object Type Declarations" level with the following meaning:

heritable: A boolean that indicates if this type is inherited automatically or if it should be explicitly declared on every type that inherit it in order to consider it as a part of it. True means the child does not need to overwrite it in order to inherite it, it is inherited automatically. False means that if the child does not overwrite it explicitly, the same won't be available on it, thus it's not usable by it, in other words, the property is not inherited automatically. Default value: true

Use Case:

types:
  entity:
    type: object
    properties:
      field1?:
        type: string
        description: field 1.
      field2?:
        type: boolean
        description: field 2.
      field3?:
        type: string
        description: field 3.	
        heritable: true
    heritable: false
   
  inheritedEntity:
    type: entity
    properties:
      field1:
      field4: number
        description: field 4.

Examples:

entity: 		# valid
  field1: "John"
  field2: true
  field3: "Doe"   
  
inheritedEntity:	# invalid because of heritable is false for entity which means by default all attributes are excluded at least it is explicitly declared on the child, and field2 is not.
  field1: "John"   
  field2: true	
  field4: 1   

inheritedEntity:	# valid because of the only available attributes are: entity.field3 and inheritedEntity.field4 and entity.field1 because of it is overwritten. The entity.field2 is not usable because it is excluded in the parent and no overwritten in the child
  field1: "John"
  field3: "Doe"    	
  field4: 1  
  
inheritedEntity:	# invalid because of  entity.field2 is not usable because it is excluded in the parent and no overwritten in the child
  field2: true
  field3: "Doe"    	
  field4: 1