Definition objects should be more informative and extensible

[resouer]

XXXDefinition will become a "register object" for given trait/workload, it worth a better design.

Part 1: Informative fields. As an end user I may expect I can get rich information by kubectl describe trait cronhpa.

For example, I will expect a description which is equivalent to --help for a given capability:

$ kubectl get trait cronhpa -o yaml
...
spec:
  definitionRef:
    name: cronhpa.alibaba-inc.com
  description: |
    CronHPA is a kubernetes cron horizontal pod autoscaler controller using `crontab` like scheme

    The cron expression format is as described below: 

    Field name   | Mandatory? | Allowed values  | Allowed special characters
    ----------   | ---------- | --------------  | --------------------------
    Seconds      | Yes        | 0-59            | * / , -
    Minutes      | Yes        | 0-59            | * / , -
    Hours        | Yes        | 0-23            | * / , -
    Day of month | Yes        | 1-31            | * / , - ?
    Month        | Yes        | 1-12 or JAN-DEC | * / , -
    Day of week  | Yes        | 0-6 or SUN-SAT  | * / , - ?   

Some other generated content from CRD/go types for description, for example:

https://doc.crds.dev/github.com/crossplane/provider-alibaba/config/crd/database.alibaba.crossplane.io_rdsinstances.yaml

https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#networkpolicy-v1-networking-k8s-io

Part 2: manageability fields, for example: workloadAware, revisionAware etc.

[resouer]

/cc @wonderflow

[resouer]

Also, definition objects should be extensible, i.e. there could be a section of extended parameters for platform builders to extend the functionality of TraitDefinition etc.

[wonderflow]

Totally agree, we can add a proposal for it in oam-k8s-runtime