SMI spec should have concrete documentation for fields in the spec

[shashankram]

SMI spec should document the spec in detail - documenting fields in the spec.

Currently, the documentation is not documenting the exact specification of the fields in the spec. The approach currently followed is to describe the spec from an example, which does not cover all possibilities.

For ex. consider the following spec:

apiVersion: metrics.smi-spec.io/v1alpha1
kind: TrafficMetrics
# See ObjectReference v1 core for full spec
resource:
  name: foo-775b9cbd88-ntxsl
  namespace: foobar
  kind: Pod
edge:
  direction: to
  side: client
  resource:
    name: baz-577db7d977-lsk2q
    namespace: foobar
    kind: Pod
timestamp: 2019-04-08T22:25:55Z
window: 30s
metrics:
- name: p99_response_latency
  unit: seconds
  value: 10m
- name: p90_response_latency
  unit: seconds
  value: 10m
- name: p50_response_latency
  unit: seconds
  value: 10m
- name: success_count
  value: 100
- name: failure_count
  value: 100

The metrics spec should clearly define what each field in the spec implies. What's name, unit, value for the metrics object is not clear reading the spec.

[alexbrand]

Looks like this issue might related/duplicate of https://github.com/servicemeshinterface/smi-spec/issues/132