From bb35aebd392a40ba909642fbde0be1fa000e51a9 Mon Sep 17 00:00:00 2001
From: Scott Nichols <nicholss@google.com>
Date: Tue, 10 Sep 2019 10:33:10 -0700
Subject: [PATCH 01/18] Adding Source concept spec.

---
 config/200-source-observer-clusterrole.yaml |  52 +++++++
 config/300-apiserversource.yaml             |   1 +
 config/300-containersource.yaml             |   1 +
 config/300-cronjobsource.yaml               |   1 +
 docs/spec/README.md                         |   4 +-
 docs/spec/sources.md                        | 147 ++++++++++++++++++++
 6 files changed, 203 insertions(+), 3 deletions(-)
 create mode 100644 config/200-source-observer-clusterrole.yaml
 create mode 100644 docs/spec/sources.md

diff --git a/config/200-source-observer-clusterrole.yaml b/config/200-source-observer-clusterrole.yaml
new file mode 100644
index 00000000000..d87b34c02eb
--- /dev/null
+++ b/config/200-source-observer-clusterrole.yaml
@@ -0,0 +1,52 @@
+# Copyright 2019 The Knative Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Use this aggregated ClusterRole when you need read "Sources".
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: source-observer
+  labels:
+    eventing.knative.dev/release: devel
+aggregationRule:
+  clusterRoleSelectors:
+    - matchLabels:
+        duck.knative.dev/source: "true"
+rules: [] # Rules are automatically filled in by the controller manager.
+
+---
+
+
+kind: ClusterRole
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+  name: containersource-source-observer
+  labels:
+    eventing.knative.dev/release: devel
+    duck.knative.dev/source: "true"
+# Do not use this role directly. These rules will be added to the "source-observer" role.
+rules:
+  - apiGroups:
+      - sources.eventing.knative.dev
+    resources:
+      - containersources
+      - containersources/status
+      - cronjobsources
+      - cronjobsources/status
+      - apiserversources
+      - apiserversources/status
+    verbs:
+      - get
+      - list
+      - watch
diff --git a/config/300-apiserversource.yaml b/config/300-apiserversource.yaml
index f02fef55bb7..82293c9e3cf 100644
--- a/config/300-apiserversource.yaml
+++ b/config/300-apiserversource.yaml
@@ -19,6 +19,7 @@ metadata:
   labels:
     eventing.knative.dev/release: devel
     eventing.knative.dev/source: "true"
+    duck.knative.dev/source: "true"
     knative.dev/crd-install: "true"
   name: apiserversources.sources.eventing.knative.dev
 spec:
diff --git a/config/300-containersource.yaml b/config/300-containersource.yaml
index a2a83f86dbf..50b6f7c2f37 100644
--- a/config/300-containersource.yaml
+++ b/config/300-containersource.yaml
@@ -18,6 +18,7 @@ metadata:
   labels:
     eventing.knative.dev/release: devel
     eventing.knative.dev/source: "true"
+    duck.knative.dev/source: "true"
     knative.dev/crd-install: "true"
   name: containersources.sources.eventing.knative.dev
 spec:
diff --git a/config/300-cronjobsource.yaml b/config/300-cronjobsource.yaml
index 3cd790db0cf..e1edd95e986 100644
--- a/config/300-cronjobsource.yaml
+++ b/config/300-cronjobsource.yaml
@@ -18,6 +18,7 @@ metadata:
   labels:
     eventing.knative.dev/release: devel
     eventing.knative.dev/source: "true"
+    duck.knative.dev/source: "true"
     knative.dev/crd-install: "true"
   name: cronjobsources.sources.eventing.knative.dev
 spec:
diff --git a/docs/spec/README.md b/docs/spec/README.md
index e46eaebbee5..eee55751c9f 100644
--- a/docs/spec/README.md
+++ b/docs/spec/README.md
@@ -16,9 +16,7 @@ Docs in this directory:
 - [Object model specification](spec.md)
 - [Channel specification](channel.md) and
   [older channel (0.6.0) spec](channel_060.md)
-
-<!-- TODO(n3wscott): * [Error conditions and reporting](errors.md) -->
-<!-- TODO(n3wscott): * [Sample API usage](normative_examples.md) -->
+- [Sources specification](sources.md)
 
 See the
 [Knative Eventing Docs Architecture](https://www.knative.dev/docs/eventing/#architecture)
diff --git a/docs/spec/sources.md b/docs/spec/sources.md
new file mode 100644
index 00000000000..26cf9cbee47
--- /dev/null
+++ b/docs/spec/sources.md
@@ -0,0 +1,147 @@
+# Sources
+
+A **source** is any resource that generates or imports an event and relays that
+event to another resource on the cluster via CloudEvents. Sourcing events is
+critical to developing a distributed system that reacts to events.
+
+A Source:
+
+- Represent an off or on-cluster system, service or application.
+- Produces or imports CloudEvents.
+- Sends CloudEvents to the configured **sink**.
+
+In practice, sources are an abstract concept that allow us to create declarative
+configurations through the usage of Custom Resource Definitions (CRDs) extending
+Kubernetes. Those CRDs are instantiated by creating a instance of the resource.
+It is up to the implementation of the source author to understand the best way
+to realize the source application. This could be as 1:1 deployments inside of
+Kubernetes per resource, as a single multi-tenant application, or even an
+off-cluster implementation; or all combinations in-between.
+
+There are some guidelines on implementing sources to allow cluster operators and
+tools to dynamically discover and understand source installations.
+
+## Source CRDs
+
+CRDs that are to be understood as a `source` must be labeled:
+
+```yaml
+apiVersion: apiextensions.k8s.io/v1beta1
+kind: CustomResourceDefinition
+metadata:
+  labels:
+    duck.knative.dev/source: "true" # <-- required to be a source.
+```
+
+CRDs should be added to the `sources` category:
+
+```yaml
+spec:
+  names:
+    categories:
+      - sources
+```
+
+<!-- TODO(n3wscott,nacho): document the registry reqirements.
+
+### Event Type Registry
+
+To be included in the event type registry:
+
+```yaml
+todo
+```
+-->
+
+## Source RBAC
+
+Knative leverages am aggregated RBAC role to allow for controllers to check the
+status of source type resources.
+
+The `source-observer` account looks like:
+
+```yaml
+# Use this aggregated ClusterRole when you need read "Sources".
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: source-observer
+aggregationRule:
+  clusterRoleSelectors:
+    - matchLabels:
+        duck.knative.dev/source: "true"
+rules: [] # Rules are automatically filled in by the controller manager.
+```
+
+And new sources should include a ClusterRoleBinding as part of installing
+themselves into a cluster:
+
+```yaml
+kind: ClusterRole
+apiVersion: rbac.authorization.k8s.io/v1
+metadata:
+  name: foos-source-observer
+  labels:
+    duck.knative.dev/source: "true"
+rules:
+  - apiGroups:
+      - example.com
+    resources:
+      - foos
+      - foos/status
+    verbs:
+      - get
+      - list
+      - watch
+```
+
+## Source Resource Shape
+
+The minimum definition of the Kubernetes resource shape is defined in the
+[Source](https://godoc.org/github.com/knative/pkg/apis/duck/v1beta1#Source)
+ducktype.
+
+### duck.Spec
+
+The `spec` field is expected to have the following minimum shape:
+
+```go
+type SourceSpec struct {
+    // Sink is a reference to an object that will resolve to a domain name or a
+    // URI directly to use as the sink.
+    Sink apisv1alpha1.Destination `json:"sink,omitempty"`
+
+    // CloudEventOverrides defines overrides to control the output format and
+    // modifications of the event sent to the sink.
+    // +optional
+    CloudEventOverrides *CloudEventOverrides `json:"ceOverrides,omitempty"`
+}
+```
+
+For a full definition of `Sink` and `CloudEventsOverrides`, please see
+[Destination](https://godoc.org/knative.dev/pkg/apis/v1alpha1#Destination), and
+[CloudEventOverrides](https://godoc.org/github.com/knative/pkg/apis/duck/v1beta1#CloudEventOverrides).
+
+### duck.Status
+
+The `status` field is expected to have the following minimum shape:
+
+```go
+type SourceStatus struct {
+    // inherits duck/v1beta1 Status, which currently provides:
+    // * ObservedGeneration - the 'Generation' of the Service that was last
+    //   processed by the controller.
+    // * Conditions - the latest available observations of a resource's current
+    //   state.
+    Status `json:",inline"`
+
+    // SinkURI is the current active sink URI that has been configured for the
+    // Source.
+    // +optional
+    SinkURI *apis.URL `json:"sinkUri,omitempty"`
+}
+```
+
+For a full definition of `Status` and `SinkURI`, please see
+[Status](https://godoc.org/github.com/knative/pkg/apis/duck/v1beta1#Status), and
+[URL](https://godoc.org/knative.dev/pkg/apis#URL).

From 557dec6ca937b4916cefd79d4d359c138198bea5 Mon Sep 17 00:00:00 2001
From: Scott Nichols <32305648+n3wscott@users.noreply.github.com>
Date: Tue, 10 Sep 2019 11:01:33 -0700
Subject: [PATCH 02/18] Update docs/spec/sources.md

Co-Authored-By: Adam Harwayne <harwayne@google.com>
---
 docs/spec/sources.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/spec/sources.md b/docs/spec/sources.md
index 26cf9cbee47..88059316dcc 100644
--- a/docs/spec/sources.md
+++ b/docs/spec/sources.md
@@ -33,7 +33,7 @@ metadata:
     duck.knative.dev/source: "true" # <-- required to be a source.
 ```
 
-CRDs should be added to the `sources` category:
+CRDs SHOULD be added to the `sources` category:
 
 ```yaml
 spec:

From b0ce5ec7795f87598cf435c399ebfa15915aa704 Mon Sep 17 00:00:00 2001
From: Scott Nichols <32305648+n3wscott@users.noreply.github.com>
Date: Tue, 10 Sep 2019 11:01:38 -0700
Subject: [PATCH 03/18] Update docs/spec/sources.md

Co-Authored-By: Adam Harwayne <harwayne@google.com>
---
 docs/spec/sources.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/spec/sources.md b/docs/spec/sources.md
index 88059316dcc..dd38fc7847c 100644
--- a/docs/spec/sources.md
+++ b/docs/spec/sources.md
@@ -23,7 +23,7 @@ tools to dynamically discover and understand source installations.
 
 ## Source CRDs
 
-CRDs that are to be understood as a `source` must be labeled:
+CRDs that are to be understood as a `source` MUST be labeled:
 
 ```yaml
 apiVersion: apiextensions.k8s.io/v1beta1

From 208420243ff947e9ba9347c4e79fe5ad30d9d07a Mon Sep 17 00:00:00 2001
From: Scott Nichols <32305648+n3wscott@users.noreply.github.com>
Date: Tue, 10 Sep 2019 11:01:44 -0700
Subject: [PATCH 04/18] Update docs/spec/sources.md

Co-Authored-By: Adam Harwayne <harwayne@google.com>
---
 docs/spec/sources.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/spec/sources.md b/docs/spec/sources.md
index dd38fc7847c..107647c4cf7 100644
--- a/docs/spec/sources.md
+++ b/docs/spec/sources.md
@@ -12,7 +12,7 @@ A Source:
 
 In practice, sources are an abstract concept that allow us to create declarative
 configurations through the usage of Custom Resource Definitions (CRDs) extending
-Kubernetes. Those CRDs are instantiated by creating a instance of the resource.
+Kubernetes. Those CRDs are instantiated by creating an instance of the resource.
 It is up to the implementation of the source author to understand the best way
 to realize the source application. This could be as 1:1 deployments inside of
 Kubernetes per resource, as a single multi-tenant application, or even an

From 0f193243f12899a6d90e8a5277047158b5fe10a8 Mon Sep 17 00:00:00 2001
From: Scott Nichols <32305648+n3wscott@users.noreply.github.com>
Date: Tue, 10 Sep 2019 11:03:27 -0700
Subject: [PATCH 05/18] Update config/200-source-observer-clusterrole.yaml

Co-Authored-By: Adam Harwayne <harwayne@google.com>
---
 config/200-source-observer-clusterrole.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/config/200-source-observer-clusterrole.yaml b/config/200-source-observer-clusterrole.yaml
index d87b34c02eb..b18d817c884 100644
--- a/config/200-source-observer-clusterrole.yaml
+++ b/config/200-source-observer-clusterrole.yaml
@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Use this aggregated ClusterRole when you need read "Sources".
+# Use this aggregated ClusterRole when you need to read "Sources".
 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
 metadata:

From 8c898ce938cda4776bb9b871e7a23a61930235c4 Mon Sep 17 00:00:00 2001
From: Scott Nichols <32305648+n3wscott@users.noreply.github.com>
Date: Tue, 10 Sep 2019 11:03:39 -0700
Subject: [PATCH 06/18] Update docs/spec/sources.md

Co-Authored-By: Adam Harwayne <harwayne@google.com>
---
 docs/spec/sources.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/spec/sources.md b/docs/spec/sources.md
index 107647c4cf7..058fee2ba68 100644
--- a/docs/spec/sources.md
+++ b/docs/spec/sources.md
@@ -73,7 +73,7 @@ aggregationRule:
 rules: [] # Rules are automatically filled in by the controller manager.
 ```
 
-And new sources should include a ClusterRoleBinding as part of installing
+And new sources MUST include a ClusterRole as part of installing
 themselves into a cluster:
 
 ```yaml

From 67f6df853be4abfc422374ec249b121f9d421fdc Mon Sep 17 00:00:00 2001
From: Scott Nichols <nicholss@google.com>
Date: Tue, 10 Sep 2019 11:23:53 -0700
Subject: [PATCH 07/18] rename observer, update text.

---
 config/200-source-observer-clusterrole.yaml | 2 +-
 docs/spec/sources.md                        | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/config/200-source-observer-clusterrole.yaml b/config/200-source-observer-clusterrole.yaml
index b18d817c884..0e56475084a 100644
--- a/config/200-source-observer-clusterrole.yaml
+++ b/config/200-source-observer-clusterrole.yaml
@@ -31,7 +31,7 @@ rules: [] # Rules are automatically filled in by the controller manager.
 kind: ClusterRole
 apiVersion: rbac.authorization.k8s.io/v1
 metadata:
-  name: containersource-source-observer
+  name: eventing-sources-source-observer
   labels:
     eventing.knative.dev/release: devel
     duck.knative.dev/source: "true"
diff --git a/docs/spec/sources.md b/docs/spec/sources.md
index 058fee2ba68..aad8085ea8a 100644
--- a/docs/spec/sources.md
+++ b/docs/spec/sources.md
@@ -73,8 +73,8 @@ aggregationRule:
 rules: [] # Rules are automatically filled in by the controller manager.
 ```
 
-And new sources MUST include a ClusterRole as part of installing
-themselves into a cluster:
+And new sources MUST include a ClusterRole as part of installing themselves into
+a cluster:
 
 ```yaml
 kind: ClusterRole

From 5ea9a8672b12f0451b4d9bc0e23ad8fc510f6feb Mon Sep 17 00:00:00 2001
From: Scott Nichols <32305648+n3wscott@users.noreply.github.com>
Date: Tue, 10 Sep 2019 11:47:58 -0700
Subject: [PATCH 08/18] Update docs/spec/sources.md

Co-Authored-By: Adam Harwayne <harwayne@google.com>
---
 docs/spec/sources.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/spec/sources.md b/docs/spec/sources.md
index aad8085ea8a..c0c95f3f2ad 100644
--- a/docs/spec/sources.md
+++ b/docs/spec/sources.md
@@ -58,7 +58,7 @@ todo
 Knative leverages am aggregated RBAC role to allow for controllers to check the
 status of source type resources.
 
-The `source-observer` account looks like:
+The [`source-observer` ClusterRole](../../config/200-source-observer-clusterrole.yaml) looks like:
 
 ```yaml
 # Use this aggregated ClusterRole when you need read "Sources".

From 8194bc949bddfde8e9862d69869588a9ab2d2365 Mon Sep 17 00:00:00 2001
From: Scott Nichols <nicholss@google.com>
Date: Wed, 11 Sep 2019 09:20:10 -0700
Subject: [PATCH 09/18] typos.

---
 docs/spec/sources.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/spec/sources.md b/docs/spec/sources.md
index aad8085ea8a..f495f754595 100644
--- a/docs/spec/sources.md
+++ b/docs/spec/sources.md
@@ -6,7 +6,8 @@ critical to developing a distributed system that reacts to events.
 
 A Source:
 
-- Represent an off or on-cluster system, service or application.
+- Represents an off or on-cluster system, service or application that produces
+  events to be consumed by a sink.
 - Produces or imports CloudEvents.
 - Sends CloudEvents to the configured **sink**.
 
@@ -55,7 +56,7 @@ todo
 
 ## Source RBAC
 
-Knative leverages am aggregated RBAC role to allow for controllers to check the
+Knative leverages an aggregated RBAC role to allow for controllers to check the
 status of source type resources.
 
 The `source-observer` account looks like:

From efabad526ba90808073877af5d2c50d9b0bcb28b Mon Sep 17 00:00:00 2001
From: Scott Nichols <nicholss@google.com>
Date: Thu, 12 Sep 2019 09:22:49 -0700
Subject: [PATCH 10/18] adding todos, will follow up to fix.

---
 config/200-source-observer-clusterrole.yaml |  1 -
 docs/spec/sources.md                        | 47 +++++++++++++++++++--
 2 files changed, 43 insertions(+), 5 deletions(-)

diff --git a/config/200-source-observer-clusterrole.yaml b/config/200-source-observer-clusterrole.yaml
index 0e56475084a..31bf7c4c0ba 100644
--- a/config/200-source-observer-clusterrole.yaml
+++ b/config/200-source-observer-clusterrole.yaml
@@ -27,7 +27,6 @@ rules: [] # Rules are automatically filled in by the controller manager.
 
 ---
 
-
 kind: ClusterRole
 apiVersion: rbac.authorization.k8s.io/v1
 metadata:
diff --git a/docs/spec/sources.md b/docs/spec/sources.md
index 157f90fdef1..6eeb7d09954 100644
--- a/docs/spec/sources.md
+++ b/docs/spec/sources.md
@@ -22,6 +22,10 @@ off-cluster implementation; or all combinations in-between.
 There are some guidelines on implementing sources to allow cluster operators and
 tools to dynamically discover and understand source installations.
 
+
+<!-- TODO: expand on CR state of a Source and those expectations. --?>
+
+
 ## Source CRDs
 
 CRDs that are to be understood as a `source` MUST be labeled:
@@ -34,6 +38,8 @@ metadata:
     duck.knative.dev/source: "true" # <-- required to be a source.
 ```
 
+<!-- TODO: Let's expand a bit on this. It would be maybe be useful to include the motivation here, for example, so support the Source in the listing (for example kubectl get ... command). So in addition to MUST be labeled, why would be helpful. Understood is just a bit of a vague term here. -->
+ 
 CRDs SHOULD be added to the `sources` category:
 
 ```yaml
@@ -43,8 +49,27 @@ spec:
       - sources
 ```
 
+<!-- TODO: We should mention consistent use of the Conditions and in particular the one Ready condition that we have defined in the apis.ConditionReady and probably add that as a recommended additional Printer Column for consistency? -->
+
+
+
+<!-- We should also talk about the validation aspects and encourage proper Description for the fields and so forth also?
+
+### Source Validation
+
+OpenAPI
+
+```yaml
+  validation:
+    openAPIV3Schema: 
+```
+
+-->
+
 <!-- TODO(n3wscott,nacho): document the registry reqirements.
 
+
+
 ### Event Type Registry
 
 To be included in the event type registry:
@@ -74,6 +99,14 @@ aggregationRule:
 rules: [] # Rules are automatically filled in by the controller manager.
 ```
 
+<!-- Might be worth it to mention a use case or two as examples? Motivation section if you will :) 
+
+### Motivation for Aggregated RBAC
+
+TODO.....
+
+-->
+
 And new sources MUST include a ClusterRole as part of installing themselves into
 a cluster:
 
@@ -99,7 +132,7 @@ rules:
 ## Source Resource Shape
 
 The minimum definition of the Kubernetes resource shape is defined in the
-[Source](https://godoc.org/github.com/knative/pkg/apis/duck/v1beta1#Source)
+[Source](https://godoc.org/github.com/knative/pkg/apis/duck/v1#Source)
 ducktype.
 
 ### duck.Spec
@@ -121,7 +154,7 @@ type SourceSpec struct {
 
 For a full definition of `Sink` and `CloudEventsOverrides`, please see
 [Destination](https://godoc.org/knative.dev/pkg/apis/v1alpha1#Destination), and
-[CloudEventOverrides](https://godoc.org/github.com/knative/pkg/apis/duck/v1beta1#CloudEventOverrides).
+[CloudEventOverrides](https://godoc.org/github.com/knative/pkg/apis/duck/v1#CloudEventOverrides).
 
 ### duck.Status
 
@@ -129,7 +162,7 @@ The `status` field is expected to have the following minimum shape:
 
 ```go
 type SourceStatus struct {
-    // inherits duck/v1beta1 Status, which currently provides:
+    // inherits duck/v1 Status, which currently provides:
     // * ObservedGeneration - the 'Generation' of the Service that was last
     //   processed by the controller.
     // * Conditions - the latest available observations of a resource's current
@@ -143,6 +176,12 @@ type SourceStatus struct {
 }
 ```
 
+<!-- TODO
+ 
+ TODO: We should probably mention here about the apis.ConditionSet and each Source IMHO should have the apis.ConditionReady as the one way to look at the readiness of the Source.
+ 
+ -->
+
 For a full definition of `Status` and `SinkURI`, please see
-[Status](https://godoc.org/github.com/knative/pkg/apis/duck/v1beta1#Status), and
+[Status](https://godoc.org/github.com/knative/pkg/apis/duck/v1#Status), and
 [URL](https://godoc.org/knative.dev/pkg/apis#URL).

From b1f59628b45ed702c0190a6cde226efa04632697 Mon Sep 17 00:00:00 2001
From: Scott Nichols <nicholss@google.com>
Date: Fri, 13 Sep 2019 08:14:26 -0700
Subject: [PATCH 11/18] checkpoint,.

---
 docs/spec/sources.md | 36 +++++++++++++++++++++++++-----------
 1 file changed, 25 insertions(+), 11 deletions(-)

diff --git a/docs/spec/sources.md b/docs/spec/sources.md
index 6eeb7d09954..8a7b2419cba 100644
--- a/docs/spec/sources.md
+++ b/docs/spec/sources.md
@@ -19,15 +19,30 @@ to realize the source application. This could be as 1:1 deployments inside of
 Kubernetes per resource, as a single multi-tenant application, or even an
 off-cluster implementation; or all combinations in-between.
 
+There are two 
+
+For an operator or a cluster to discover  
+
+There is a distinction between a Kubernetes cluster that has a source CRD installed
+and a custom resource (CR is an instance of a CRD). A cluster that has a source CRD 
+installed has the ability to signal to the cluster operator that it is capable of
+producing events of a certain type by using the [Event Type Registry](#event-type-registry).
+
+
+
 There are some guidelines on implementing sources to allow cluster operators and
 tools to dynamically discover and understand source installations.
 
-
 <!-- TODO: expand on CR state of a Source and those expectations. --?>
 
 
 ## Source CRDs
 
+Sources are more useful if they are discoverable. Knative Sources MUST use a
+ducktype label to allow controllers and operators the ability to find which
+CRDs are considered to be adhering to the
+[Source](https://godoc.org/github.com/knative/pkg/apis/duck/v1#Source) ducktype. 
+
 CRDs that are to be understood as a `source` MUST be labeled:
 
 ```yaml
@@ -39,7 +54,7 @@ metadata:
 ```
 
 <!-- TODO: Let's expand a bit on this. It would be maybe be useful to include the motivation here, for example, so support the Source in the listing (for example kubectl get ... command). So in addition to MUST be labeled, why would be helpful. Understood is just a bit of a vague term here. -->
- 
+
 CRDs SHOULD be added to the `sources` category:
 
 ```yaml
@@ -51,8 +66,6 @@ spec:
 
 <!-- TODO: We should mention consistent use of the Conditions and in particular the one Ready condition that we have defined in the apis.ConditionReady and probably add that as a recommended additional Printer Column for consistency? -->
 
-
-
 <!-- We should also talk about the validation aspects and encourage proper Description for the fields and so forth also?
 
 ### Source Validation
@@ -61,7 +74,7 @@ OpenAPI
 
 ```yaml
   validation:
-    openAPIV3Schema: 
+    openAPIV3Schema:
 ```
 
 -->
@@ -84,7 +97,9 @@ todo
 Knative leverages an aggregated RBAC role to allow for controllers to check the
 status of source type resources.
 
-The [`source-observer` ClusterRole](../../config/200-source-observer-clusterrole.yaml) looks like:
+The
+[`source-observer` ClusterRole](../../config/200-source-observer-clusterrole.yaml)
+looks like:
 
 ```yaml
 # Use this aggregated ClusterRole when you need read "Sources".
@@ -99,7 +114,7 @@ aggregationRule:
 rules: [] # Rules are automatically filled in by the controller manager.
 ```
 
-<!-- Might be worth it to mention a use case or two as examples? Motivation section if you will :) 
+<!-- Might be worth it to mention a use case or two as examples? Motivation section if you will :)
 
 ### Motivation for Aggregated RBAC
 
@@ -132,8 +147,7 @@ rules:
 ## Source Resource Shape
 
 The minimum definition of the Kubernetes resource shape is defined in the
-[Source](https://godoc.org/github.com/knative/pkg/apis/duck/v1#Source)
-ducktype.
+[Source](https://godoc.org/github.com/knative/pkg/apis/duck/v1#Source) ducktype.
 
 ### duck.Spec
 
@@ -177,9 +191,9 @@ type SourceStatus struct {
 ```
 
 <!-- TODO
- 
+
  TODO: We should probably mention here about the apis.ConditionSet and each Source IMHO should have the apis.ConditionReady as the one way to look at the readiness of the Source.
- 
+
  -->
 
 For a full definition of `Status` and `SinkURI`, please see

From be19b25e980ba31b1bec933355fa903f5a1e7d7c Mon Sep 17 00:00:00 2001
From: Scott Nichols <nicholss@google.com>
Date: Mon, 16 Sep 2019 10:01:15 -0700
Subject: [PATCH 12/18] added more details around CRD and runtime of sources.

---
 docs/spec/sources.md | 223 ++++++++++++++++++++++++++++++++++---------
 1 file changed, 180 insertions(+), 43 deletions(-)

diff --git a/docs/spec/sources.md b/docs/spec/sources.md
index 8a7b2419cba..bfc2aa10bca 100644
--- a/docs/spec/sources.md
+++ b/docs/spec/sources.md
@@ -19,29 +19,39 @@ to realize the source application. This could be as 1:1 deployments inside of
 Kubernetes per resource, as a single multi-tenant application, or even an
 off-cluster implementation; or all combinations in-between.
 
-There are two 
+For Kubernetes Operators, there are two states to sources:
 
-For an operator or a cluster to discover  
+1. A source CRD and controller (if required) have been installed into the
+   cluster.
 
-There is a distinction between a Kubernetes cluster that has a source CRD installed
-and a custom resource (CR is an instance of a CRD). A cluster that has a source CRD 
-installed has the ability to signal to the cluster operator that it is capable of
-producing events of a certain type by using the [Event Type Registry](#event-type-registry).
+   A cluster with a source CRD installed allows the other operators in the
+   cluster to find and discover what is possible to source events from. These
+   CRDs define the credentials, input parameters, k8s categories, event types,
+   duck types, and aggregated RBAC roles required to interpret the source as the
+   source author expects. This topic is expanded upon in the
+   [Source CRDs](#source-crds) section.
 
+1. A source custom object has been created in the cluster.
 
+   Once a cluster operator creates an instance of a source and provides the
+   necessary credentials, input parameters, and event sink, the source
+   controller will realize this into whatever is required for that source for
+   the current situation. While this resource is running, a cluster operator
+   would like to inspect the resource without needing to be fully aware of the
+   implementation. This is done by conforming to the [Source]() ducktype. This
+   topic is expanded upon in the [Source Custom Objects](#source-custom-objects)
+   section.
 
-There are some guidelines on implementing sources to allow cluster operators and
-tools to dynamically discover and understand source installations.
-
-<!-- TODO: expand on CR state of a Source and those expectations. --?>
-
+The goal of requiring CRD labels and running resource shapes is to aid in
+discovery and understanding of potential sources that could be leveraged in the
+cluster, and sources that exist and are running in the cluster.
 
 ## Source CRDs
 
 Sources are more useful if they are discoverable. Knative Sources MUST use a
-ducktype label to allow controllers and operators the ability to find which
-CRDs are considered to be adhering to the
-[Source](https://godoc.org/github.com/knative/pkg/apis/duck/v1#Source) ducktype. 
+ducktype label to allow controllers and operators the ability to find which CRDs
+are considered to be adhering to the
+[Source](https://godoc.org/github.com/knative/pkg/apis/duck/v1#Source) ducktype.
 
 CRDs that are to be understood as a `source` MUST be labeled:
 
@@ -53,7 +63,13 @@ metadata:
     duck.knative.dev/source: "true" # <-- required to be a source.
 ```
 
-<!-- TODO: Let's expand a bit on this. It would be maybe be useful to include the motivation here, for example, so support the Source in the listing (for example kubectl get ... command). So in addition to MUST be labeled, why would be helpful. Understood is just a bit of a vague term here. -->
+Labeling sources in this way allows for cluster operators to list CRDs and
+filter on which ones are choosing to adhere to the source ducktype. To make this
+query,
+
+```shell
+kubectl get crds -l duck.knative.dev/source=true
+```
 
 CRDs SHOULD be added to the `sources` category:
 
@@ -64,38 +80,173 @@ spec:
       - sources
 ```
 
-<!-- TODO: We should mention consistent use of the Conditions and in particular the one Ready condition that we have defined in the apis.ConditionReady and probably add that as a recommended additional Printer Column for consistency? -->
+By adding to the sources category, we give an easy way to list running sources
+in the cluster with,
+
+```shell
+kubectl get sources
+```
+
+Source CRDs SHOULD provide additional printer columns to provide useful feedback
+to cluster operators. For example, if the resource is long-lived, it would be a
+good choice to show the `Ready` status and `Reason`, as well as the `Age` of the
+resource.
 
-<!-- We should also talk about the validation aspects and encourage proper Description for the fields and so forth also?
+```yaml
+additionalPrinterColumns:
+  - name: Ready
+    type: string
+    JSONPath: '.status.conditions[?(@.type=="Ready")].status'
+  - name: Reason
+    type: string
+    JSONPath: '.status.conditions[?(@.type=="Ready")].reason'
+  - name: Age
+    type: date
+    JSONPath: .metadata.creationTimestamp
+```
 
 ### Source Validation
 
-OpenAPI
+Sources MUST implement conditions with a `Ready` condition for long lived
+sources, and `Succeeded` for batch style sources.
+
+Sources MUST propagate the `sinkUri` to their status to signal to the cluster
+where their events are being sent.
+
+Knative has standardized on the following minimum OpenAPI definition of `status`
+for Source CRDs:
 
 ```yaml
-  validation:
-    openAPIV3Schema:
+validation:
+  openAPIV3Schema:
+    properties:
+      status:
+        type: object
+        properties:
+          conditions:
+            type: array
+            items:
+              type: object
+              properties:
+                lastTransitionTime:
+                  type: string
+                message:
+                  type: string
+                reason:
+                  type: string
+                severity:
+                  type: string
+                status:
+                  type: string
+                type:
+                  type: string
+              required:
+                - type
+                - status
+          sinkUri:
+            type: string
 ```
 
--->
-
-<!-- TODO(n3wscott,nacho): document the registry reqirements.
+Please see
+[SourceStatus](https://godoc.org/github.com/knative/pkg/apis/duck/v1#SourceStatus)
+and [Condition](https://godoc.org/github.com/knative/pkg/apis/#Condition) for
+more details.
 
+Sources SHOULD provide OpenAPI validation for the `spec` field. At minimum
+sources SHOULD have the following,
 
+```yaml
+validation:
+  openAPIV3Schema:
+    properties:
+      spec:
+        type: object
+        required:
+          - sink
+        properties:
+          sink:
+            type: object
+            description:
+              "Reference to an object that will resolve to a domain name to use
+              as the sink."
+          ceOverrides:
+            type: object
+            description:
+              "Defines overrides to control modifications of the event sent to
+              the sink."
+            properties:
+              extensions:
+                type: object
+                description:
+                  "Extensions specify what attribute are added or overridden on
+                  the outbound event. Each `Extensions` key-value pair are set
+                  on the event as an attribute extension independently."
+```
 
 ### Event Type Registry
 
-To be included in the event type registry:
+The Event Type Registry is a feature that allows for software to find all CRDs
+labeled as a `Source` ducktype, and extract the defined
+[EventType](https://godoc.org/knative.dev/eventing/pkg/apis/eventing/v1alpha1#EventType)s
+that could be emitted from a source instance.
+
+To be included in the event type registry a fake `registry` component is defined
+in the `openAPIV3Schema` section inside the CRD. It is not our intention to have
+cluster operators create resources with this filled out, it is to signal to
+other software some metadata about the runtime/dataplane characteristics of this
+type of source.
+
+As an example, here is a snip the registry entry for ApiServerSource, a source
+that emits Kubernetes event,
 
 ```yaml
-todo
+  validation:
+    openAPIV3Schema:
+      properties:
+        registry:
+          type: object
+          description: "Internal information, users should not set this property"
+          properties:
+            eventTypes:
+              type: object
+              description: "Event types that ApiServerSource can produce"
+              properties:
+                addResource:
+                  type: object
+                  properties:
+                    type:
+                      type: string
+                      pattern: "dev.knative.apiserver.resource.add"
+                    schema:
+                      type: string
+                deleteResource:
+                  type: object
+                  properties:
+                    type:
+                      type: string
+                      pattern: "dev.knative.apiserver.resource.delete"
+                    schema:
+                      type: string
+                updateResource:
+                  type: object
+                  properties:
+                    type:
+                      type: string
+                      pattern: "dev.knative.apiserver.resource.update"
+                    schema:
+                      type: string
+                ...
 ```
--->
 
 ## Source RBAC
 
-Knative leverages an aggregated RBAC role to allow for controllers to check the
-status of source type resources.
+Sources can by any shape and are expected to be extensions onto Kubernetes. To
+prevent cluster operators from re-deploying, or re-creating RBAC for all
+accounts that will interact with sources, Knative leverages aggregated RBAC
+roles to dynamically update the rights of controllers that are using common
+service accounts provided by Knative. This allows Eventing controllers to to
+check the status of source type resources without being aware of the exact
+source type or implementation at compile time.
 
 The
 [`source-observer` ClusterRole](../../config/200-source-observer-clusterrole.yaml)
@@ -114,14 +265,6 @@ aggregationRule:
 rules: [] # Rules are automatically filled in by the controller manager.
 ```
 
-<!-- Might be worth it to mention a use case or two as examples? Motivation section if you will :)
-
-### Motivation for Aggregated RBAC
-
-TODO.....
-
--->
-
 And new sources MUST include a ClusterRole as part of installing themselves into
 a cluster:
 
@@ -144,7 +287,7 @@ rules:
       - watch
 ```
 
-## Source Resource Shape
+## Source Custom Objects
 
 The minimum definition of the Kubernetes resource shape is defined in the
 [Source](https://godoc.org/github.com/knative/pkg/apis/duck/v1#Source) ducktype.
@@ -190,12 +333,6 @@ type SourceStatus struct {
 }
 ```
 
-<!-- TODO
-
- TODO: We should probably mention here about the apis.ConditionSet and each Source IMHO should have the apis.ConditionReady as the one way to look at the readiness of the Source.
-
- -->
-
 For a full definition of `Status` and `SinkURI`, please see
 [Status](https://godoc.org/github.com/knative/pkg/apis/duck/v1#Status), and
 [URL](https://godoc.org/knative.dev/pkg/apis#URL).

From 16dd72c82b2ec2958588a0041a86bc551aa40ee0 Mon Sep 17 00:00:00 2001
From: Scott Nichols <nicholss@google.com>
Date: Mon, 16 Sep 2019 10:48:01 -0700
Subject: [PATCH 13/18] remove the to to.

---
 docs/spec/sources.md | 6 +++---
 docs/spec/spec.md    | 6 +++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/spec/sources.md b/docs/spec/sources.md
index bfc2aa10bca..d3f5c30f201 100644
--- a/docs/spec/sources.md
+++ b/docs/spec/sources.md
@@ -244,9 +244,9 @@ Sources can by any shape and are expected to be extensions onto Kubernetes. To
 prevent cluster operators from re-deploying, or re-creating RBAC for all
 accounts that will interact with sources, Knative leverages aggregated RBAC
 roles to dynamically update the rights of controllers that are using common
-service accounts provided by Knative. This allows Eventing controllers to to
-check the status of source type resources without being aware of the exact
-source type or implementation at compile time.
+service accounts provided by Knative. This allows Eventing controllers to check
+the status of source type resources without being aware of the exact source type
+or implementation at compile time.
 
 The
 [`source-observer` ClusterRole](../../config/200-source-observer-clusterrole.yaml)
diff --git a/docs/spec/spec.md b/docs/spec/spec.md
index 7e44781b800..b25cfb136c7 100644
--- a/docs/spec/spec.md
+++ b/docs/spec/spec.md
@@ -68,9 +68,9 @@ Trigger._
 
 #### Spec
 
-| Field           | Type        | Description                                                                                                        | Constraints                                      |
-| --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
-| channelTemplate | ChannelSpec | The template used to create Channels internal to the Broker. Defaults to to the default Channel for the namespace. | Only Provisioner and Arguments may be specified. |
+| Field           | Type        | Description                                                                                                     | Constraints                                      |
+| --------------- | ----------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| channelTemplate | ChannelSpec | The template used to create Channels internal to the Broker. Defaults to the default Channel for the namespace. | Only Provisioner and Arguments may be specified. |
 
 #### Status
 

From 5f43d0ed1db2dd56d61a6d019a540a73631b564d Mon Sep 17 00:00:00 2001
From: Scott Nichols <nicholss@google.com>
Date: Wed, 18 Sep 2019 07:51:15 -0700
Subject: [PATCH 14/18] no need to give read on /status.

---
 config/200-source-observer-clusterrole.yaml | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/config/200-source-observer-clusterrole.yaml b/config/200-source-observer-clusterrole.yaml
index 31bf7c4c0ba..99203f7bd08 100644
--- a/config/200-source-observer-clusterrole.yaml
+++ b/config/200-source-observer-clusterrole.yaml
@@ -40,11 +40,8 @@ rules:
       - sources.eventing.knative.dev
     resources:
       - containersources
-      - containersources/status
       - cronjobsources
-      - cronjobsources/status
       - apiserversources
-      - apiserversources/status
     verbs:
       - get
       - list

From 851c857c8c93a69459e84d0506f05b6b01705a7d Mon Sep 17 00:00:00 2001
From: Scott Nichols <nicholss@google.com>
Date: Wed, 18 Sep 2019 07:52:08 -0700
Subject: [PATCH 15/18] no need to give read on /status.

---
 docs/spec/sources.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/spec/sources.md b/docs/spec/sources.md
index d3f5c30f201..d8b31c26a45 100644
--- a/docs/spec/sources.md
+++ b/docs/spec/sources.md
@@ -280,7 +280,6 @@ rules:
       - example.com
     resources:
       - foos
-      - foos/status
     verbs:
       - get
       - list

From b315642d92981cca493a4e52072b35951d790829 Mon Sep 17 00:00:00 2001
From: Scott Nichols <nicholss@google.com>
Date: Wed, 18 Sep 2019 07:59:35 -0700
Subject: [PATCH 16/18] comment out the registry section for now until we come
 to consensus.

---
 docs/spec/sources.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/spec/sources.md b/docs/spec/sources.md
index d8b31c26a45..7ca7d6db247 100644
--- a/docs/spec/sources.md
+++ b/docs/spec/sources.md
@@ -183,6 +183,10 @@ validation:
                   on the event as an attribute extension independently."
 ```
 
+<!-- 
+
+TODO: There is still debate about how to implement the registry. Commenting out for now.
+
 ### Event Type Registry
 
 The Event Type Registry is a feature that allows for software to find all CRDs
@@ -237,6 +241,7 @@ that emits Kubernetes event,
                       type: string
                 ...
 ```
+-->
 
 ## Source RBAC
 

From 5fe57df4c36b1c5baef9bddd1d422228637b228f Mon Sep 17 00:00:00 2001
From: Scott Nichols <nicholss@google.com>
Date: Wed, 18 Sep 2019 08:03:27 -0700
Subject: [PATCH 17/18] bot nit.

---
 docs/spec/sources.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/spec/sources.md b/docs/spec/sources.md
index 7ca7d6db247..c323cf8931e 100644
--- a/docs/spec/sources.md
+++ b/docs/spec/sources.md
@@ -183,7 +183,7 @@ validation:
                   on the event as an attribute extension independently."
 ```
 
-<!-- 
+<!--
 
 TODO: There is still debate about how to implement the registry. Commenting out for now.
 

From 30b37269dbbecb66f065fcc7d4df74f3197ae408 Mon Sep 17 00:00:00 2001
From: Scott Nichols <nicholss@google.com>
Date: Mon, 7 Oct 2019 09:43:37 -0700
Subject: [PATCH 18/18] updated wording from good feedback.

---
 docs/spec/README.md  |   1 +
 docs/spec/sources.md | 168 +++++++++++++++----------------------------
 2 files changed, 58 insertions(+), 111 deletions(-)

diff --git a/docs/spec/README.md b/docs/spec/README.md
index eee55751c9f..573b9e5394b 100644
--- a/docs/spec/README.md
+++ b/docs/spec/README.md
@@ -17,6 +17,7 @@ Docs in this directory:
 - [Channel specification](channel.md) and
   [older channel (0.6.0) spec](channel_060.md)
 - [Sources specification](sources.md)
+- [Error conditions and reporting](https://knative.dev/docs/serving/spec/knative-api-specification-1.0/#error-signalling)
 
 See the
 [Knative Eventing Docs Architecture](https://www.knative.dev/docs/eventing/#architecture)
diff --git a/docs/spec/sources.md b/docs/spec/sources.md
index c323cf8931e..f64311e6e78 100644
--- a/docs/spec/sources.md
+++ b/docs/spec/sources.md
@@ -1,56 +1,60 @@
 # Sources
 
-A **source** is any resource that generates or imports an event and relays that
-event to another resource on the cluster via CloudEvents. Sourcing events is
-critical to developing a distributed system that reacts to events.
+A **Source** is any Kubernetes object that generates or imports an event and
+relays that event to another endpoint on the cluster via
+[CloudEvents](https://cloudevents.io). Sourcing events is critical to developing
+a distributed system that reacts to events.
+
+A **Sink** is an [_addressable_](./interfaces.md#addressable) resource that
+takes responsibility for the event. A **Sink** could be a consumer of events, or
+middleware. A **Sink** will respond with 2xx when it has accepted and processed
+the event.
 
 A Source:
 
-- Represents an off or on-cluster system, service or application that produces
-  events to be consumed by a sink.
+- Represents an off- or on-cluster system, service or application that produces
+  events to be consumed by a **Sink**.
 - Produces or imports CloudEvents.
-- Sends CloudEvents to the configured **sink**.
+- Sends CloudEvents to the configured **Sink**.
 
 In practice, sources are an abstract concept that allow us to create declarative
 configurations through the usage of Custom Resource Definitions (CRDs) extending
-Kubernetes. Those CRDs are instantiated by creating an instance of the resource.
-It is up to the implementation of the source author to understand the best way
-to realize the source application. This could be as 1:1 deployments inside of
-Kubernetes per resource, as a single multi-tenant application, or even an
-off-cluster implementation; or all combinations in-between.
+Kubernetes. Source systems are configured by creating an instance of the
+resource described by the CRD. It is up to the implementation of the source
+author to understand the best way to realize the source application. This could
+be as 1:1 deployments inside of Kubernetes per resource, as a single
+multi-tenant application, or even an off-cluster implementation; or all
+combinations in-between.
 
-For Kubernetes Operators, there are two states to sources:
+For operators of a Kubernetes cluster, there are two states to sources:
 
-1. A source CRD and controller (if required) have been installed into the
+1. A Source CRD and controller (if required) have been installed into the
    cluster.
 
-   A cluster with a source CRD installed allows the other operators in the
-   cluster to find and discover what is possible to source events from. These
-   CRDs define the credentials, input parameters, k8s categories, event types,
-   duck types, and aggregated RBAC roles required to interpret the source as the
-   source author expects. This topic is expanded upon in the
-   [Source CRDs](#source-crds) section.
-
-1. A source custom object has been created in the cluster.
-
-   Once a cluster operator creates an instance of a source and provides the
-   necessary credentials, input parameters, and event sink, the source
-   controller will realize this into whatever is required for that source for
-   the current situation. While this resource is running, a cluster operator
-   would like to inspect the resource without needing to be fully aware of the
-   implementation. This is done by conforming to the [Source]() ducktype. This
-   topic is expanded upon in the [Source Custom Objects](#source-custom-objects)
-   section.
-
-The goal of requiring CRD labels and running resource shapes is to aid in
+   A cluster with a source CRD installed allows the developers in the cluster to
+   find and discover what is possible to source events from. This topic is
+   expanded upon in the [Source CRDs](#source-crds) section.
+
+1. A Source custom object has been created in the cluster.
+
+   Once a developer creates an instance of a source and provides the necessary
+   parameters, the source controller will realize this into whatever is required
+   for that source for the current situation. While this resource is running, a
+   cluster operator would like to inspect the resource without needing to be
+   fully aware of the implementation. This is done by conforming to the
+   [Source]() ducktype. This topic is expanded upon in the
+   [Source Custom Objects](#source-custom-objects) section.
+
+The goal of requiring CRD labels and running resource shapes is to enable
 discovery and understanding of potential sources that could be leveraged in the
-cluster, and sources that exist and are running in the cluster.
+cluster. This structure also aids in understanding sources that exist and are
+running in the cluster.
 
 ## Source CRDs
 
 Sources are more useful if they are discoverable. Knative Sources MUST use a
-ducktype label to allow controllers and operators the ability to find which CRDs
-are considered to be adhering to the
+standardized label to allow controllers and operators the ability to find which
+CRDs are considered to be adhering to the
 [Source](https://godoc.org/github.com/knative/pkg/apis/duck/v1#Source) ducktype.
 
 CRDs that are to be understood as a `source` MUST be labeled:
@@ -63,9 +67,7 @@ metadata:
     duck.knative.dev/source: "true" # <-- required to be a source.
 ```
 
-Labeling sources in this way allows for cluster operators to list CRDs and
-filter on which ones are choosing to adhere to the source ducktype. To make this
-query,
+Labeling sources in this way allows for developers to filter the list of CRDs:
 
 ```shell
 kubectl get crds -l duck.knative.dev/source=true
@@ -81,7 +83,7 @@ spec:
 ```
 
 By adding to the sources category, we give an easy way to list running sources
-in the cluster with,
+in the cluster with:
 
 ```shell
 kubectl get sources
@@ -178,80 +180,22 @@ validation:
               extensions:
                 type: object
                 description:
-                  "Extensions specify what attribute are added or overridden on
+                  "Extensions specify what attributes are added or overridden on
                   the outbound event. Each `Extensions` key-value pair are set
-                  on the event as an attribute extension independently."
+                  on the event as an extension attribute independently."
 ```
 
-<!--
-
-TODO: There is still debate about how to implement the registry. Commenting out for now.
-
-### Event Type Registry
-
-The Event Type Registry is a feature that allows for software to find all CRDs
-labeled as a `Source` ducktype, and extract the defined
-[EventType](https://godoc.org/knative.dev/eventing/pkg/apis/eventing/v1alpha1#EventType)s
-that could be emitted from a source instance.
-
-To be included in the event type registry a fake `registry` component is defined
-in the `openAPIV3Schema` section inside the CRD. It is not our intention to have
-cluster operators create resources with this filled out, it is to signal to
-other software some metadata about the runtime/dataplane characteristics of this
-type of source.
-
-As an example, here is a snip the registry entry for ApiServerSource, a source
-that emits Kubernetes event,
-
-```yaml
-  validation:
-    openAPIV3Schema:
-      properties:
-        registry:
-          type: object
-          description: "Internal information, users should not set this property"
-          properties:
-            eventTypes:
-              type: object
-              description: "Event types that ApiServerSource can produce"
-              properties:
-                addResource:
-                  type: object
-                  properties:
-                    type:
-                      type: string
-                      pattern: "dev.knative.apiserver.resource.add"
-                    schema:
-                      type: string
-                deleteResource:
-                  type: object
-                  properties:
-                    type:
-                      type: string
-                      pattern: "dev.knative.apiserver.resource.delete"
-                    schema:
-                      type: string
-                updateResource:
-                  type: object
-                  properties:
-                    type:
-                      type: string
-                      pattern: "dev.knative.apiserver.resource.update"
-                    schema:
-                      type: string
-                ...
-```
--->
+<!-- TOOD(#1550): Follow-up with a registry implementation. -->
 
 ## Source RBAC
 
-Sources can by any shape and are expected to be extensions onto Kubernetes. To
-prevent cluster operators from re-deploying, or re-creating RBAC for all
-accounts that will interact with sources, Knative leverages aggregated RBAC
-roles to dynamically update the rights of controllers that are using common
-service accounts provided by Knative. This allows Eventing controllers to check
-the status of source type resources without being aware of the exact source type
-or implementation at compile time.
+Sources are expected to be extensions onto Kubernetes. To prevent cluster
+operators from duplicating RBAC for all accounts that will interact with
+sources, cluster operators should leverage aggregated RBAC roles to dynamically
+update the rights of controllers that are using common service accounts provided
+by Knative. This allows Eventing controllers to check the status of source type
+resources without being aware of the exact source type or implementation at
+compile time.
 
 The
 [`source-observer` ClusterRole](../../config/200-source-observer-clusterrole.yaml)
@@ -266,7 +210,7 @@ metadata:
 aggregationRule:
   clusterRoleSelectors:
     - matchLabels:
-        duck.knative.dev/source: "true"
+        duck.knative.dev/source: "true" # Matched by source-observer ClusterRole
 rules: [] # Rules are automatically filled in by the controller manager.
 ```
 
@@ -293,8 +237,9 @@ rules:
 
 ## Source Custom Objects
 
-The minimum definition of the Kubernetes resource shape is defined in the
+All Source custom objects MUST implement the
 [Source](https://godoc.org/github.com/knative/pkg/apis/duck/v1#Source) ducktype.
+Additional data in spec and status is explicitly permitted.
 
 ### duck.Spec
 
@@ -313,8 +258,9 @@ type SourceSpec struct {
 }
 ```
 
-For a full definition of `Sink` and `CloudEventsOverrides`, please see
-[Destination](https://godoc.org/knative.dev/pkg/apis/v1alpha1#Destination), and
+For a golang structure definition of `Sink` and `CloudEventsOverrides`, please
+see [Destination](https://godoc.org/knative.dev/pkg/apis/v1alpha1#Destination),
+and
 [CloudEventOverrides](https://godoc.org/github.com/knative/pkg/apis/duck/v1#CloudEventOverrides).
 
 ### duck.Status